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PREFACE 


The I/O System is the part of the IRMX 86 Operating System and the 
iRMX 88 Real-Time Multitasking Executive that provides you with the 
capability of accessing files on peripheral devices. Each of these I/O 
Systems is Implemented as a set of file drivers and a set of device 
drivers. A file driver provides user access to a particular type of 
file. Independent of the device on which the file resides. A device 
driver provides a standard interface between a particular device and one 
or more file drivers. Thus, by adding device drivers, your application 
system can support additional types of devices. And it can do this 
without changing the user interface, since the file drivers remain 
unchanged. 

This manual describes how to write device drivers to interface with the 
I/O Systems. It illustrates the basic concepts of device drivers and 
describes the different types of device drivers (common, random access, 
and custom). 


READER LEVEL 

This manual assumes that you are a systems-level programmer experienced 
in dealing with I/O devices. In particular, it assumes that you are 
familiar with the following; 

• The PL/M-86 programming language and/or the MCS-86 Macro 
Assembly Language. 

• The hardware codes necessary to perform actual read and write 
operations on your I/O device. This manual does not document 
these device-dependent instructions. 

If you plan to write a device driver that uses IRMX 86 system calls, you 
should be familiar with the following, as well; 

• The IRMX 86 Operating System and the concepts of tasks, 
segments, and other objects. 

• The I/O System, as described in the iRMX 86 Basic I/O SYSTEM 
REFERENCE MANUAL. This manual documents the user interface to 
the I/O System. 

• Regions, as described in the iRMX 86 SYSTEM PROGRAMMER’S 
REFERENCE MANUAL. 

And if you plan to write a device driver that uses iRMX 88 functions or 
system calls, you should be familiar with the IRMX 88 Reference Manual. 
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CHAPTER 1. INTRODUCTION 


The iRMX 86 and IRMX 88 I/O Systems are each Implemented as a set of file 
drivers and a set of device drivers. File drivers provide the support 
for particular types of files (for example, the named file driver 
provides the support needed in order to use named files). Device drivers 
provide the support for particular devices (for example, an iSBC 215 
device driver provides the facilities that enable an iSBC 215 Winchester 
drive to be used with the I/O System). Each type of file has its own 
file driver and each device has its own device driver. 

One of the reasons that the I/O Systems are broken up in this manner is 
to provide device-independent I/O. Application tasks communicate with 
file drivers, not with device drivers. This allows tasks to manipulate 
all files in the same manner, regardless of the devices on which they 
reside. File drivers, in turn, communicate with device drivers, which 
provide the instructions necessary to manipulate physical devices. 

Figure 1-1 shows these levels of communication. 


APPLICATION TASK 


file Independent Interface 


FILE DRIVER 


device Independent interface 


DEVICE DRIVER 


DEVICE 


Figure 1-1. Communication Levels 


1-1 










INTRODUCTION 


The I/O System provides a standard interface between file drivers and 
device drivers. To a file driver, a device is merely a standard block of 
data in a table. In order to manipulate a device, the file driver calls 
the device driver procedures listed in the table. To a device driver, all 
file drivers seem the same. Every file driver calls device drivers in 
the same manner. This means that the device driver does not need to 
concern itself with the concept of a file driver. It sees Itself as 
being called by the I/O System and it returns information to the I/O 
System. This standard interface has the following advantages: 

• The hardware configuration can be changed without extensive 
modifications to the software. Instead of modifying entire file 
drivers when you want to change devices, you need only substitute 
a different device driver and modify the table. 

• The I/O System can support a greater range of devices. It can 
support any device as long as you can provide for the device a 
driver that interfaces to the file drivers in the standard manner. 


I/O DEVICES AND DEVICE DRIVERS 


Each I/O device consists of a controller and one or more units. A device 
as a whole is identified by a device number. Units are identified by 
unit number and device-unit number. The unit number identifies the unit 
within the device and the device-unit number identifies the unit among 
all the units of all of the devices. Figure 1-2 contains a simplified 
drawing of three I/O devices and their device, unit, and device-unit 
numbers. 


DEVICE 0 DEVICE 1 DEVICE 2 



Figure 1-2. Device Numbering 
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INTRODUCTION 


You must provide a device driver for every device in your hardware 
configuration. That device driver must handle the I/O requests for all 
of the units the device supports. Different devices can use different 
device drivers; or if they are the same kind of device, they can share 
the same device driver code. (For example, two iSBC 215 controllers are 
two separate devices and each has its own device driver. However, these 
device drivers share common code.) 


I/O REQUESTS 


To the device driver, an I/O request is a request by the I/O System for 
the device to perform a certain operation. Operations supported by the 
I/O System are: 

Read 

Write 

Seek 

Special 

Attach device 

Detach device 

Open 

Close 

The I/O System makes an I/O request by sending an I/O request/result 
segment (lORS) containing the necessary Information to the device 
driver. (The lORS is described in Chapter 2.) The device driver must 
translate this request into commands to the device in order to cause the 
device to perform the requested operation. 


TYPES OF DEVICE DRIVERS 


The I/O System supports three types of device drivers: custom, common, 
and random access. A custom device driver is one that the user creates 
in its entirety. This type of device driver may assume any form and may 
provide any functions that the user wishes, as long as the I/O System can 
access it by calling four procedures, designated as Initialize I/O, 

Finish I/O, Queue I/O, and Cancel I/O. 

The I/O System provides the basic support routines for the common and 
random access device driver types. These support routines provide a 
queueing mechanism, an Interrupt handler, and other features needed by 
common or random access devices. If your device fits into the common or 
random access device classification, you need to write only the 
specialized, device Hlependent procedures and interface them to the ones 
provided by the I/O System in order to create a complete device driver. 
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HOW TO READ THIS MANUAL 


This manual is for people who plan to write device drivers for use with 
iRMX 86- and/or iRMX 88-based systems. Because there are numerous 
terminology differences between the two iRMX systems, the tone of this 
manual is general, unlike that of other manuals for either system. For 
iRMX 88 users, this should not be a problem, but iRMX 86 users should 
take note of the following: 

• In a number of places the phrase "the location of" is substituted 
for "a token for". 

• The "device data storage area" that is alluded to in many places 
is actually an iRMX 86 segment. 

• The term "resources" usually means "objects". It is clear from 
context which meaning is intended for the word "resources". 


1-4 


CHAPTER 2. DEVICE DRIVER INTERFACES 


Because a device driver is a collection of software routines that manages 
a device at a basic level, it must transform general instructions from 
the I/O System into device-specific instructions which it then sends to 
the device itself. Thus a device driver has two types of interfaces: an 
interface to the I/O System, which is the same for all device drivers, 
and an Interface to the device itself, which varies according to device. 
This chapter discusses these interfaces. 


I/O SYSTEM INTERFACES 


The interface between the device driver and the I/O System consists of 
two data structures, the device-unit information block (DUIB) and the I/O 
request/result segment (lORS). 


DEVICE-UNIT INFORMATION BLOCK (DUIB) 

The DUIB is an Interface between a device driver and the I/O System in 
the sense that the DUIB contains the addresses of the device driver 
routines. By accessing the DUIB for a unit, the I/O System can call the 
appropriate device driver. All devices, no matter how diverse, use this 
standard interface to the I/O System. You must provide a DUIB for each 
device-unit in your hardware system. You supply the information for your 
DUIBs as part of the configuration process. 


DUIB Structure 

The structure of the DUIB is defined as follows: 
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DECLARE 

DEV$UNIT$INFO$BLOCK STRUCTURE( 


NAME(14) 

BYTE, 

FILE$DRIVERS 

WORD, 

FUNCTS 

BYTE, 

FLAGS 

BYTE, 

DEV$GRAN 

WORD, 

L0W$DEV$SIZE 

WORD, 

HIGH$DEV$SIZE 

WORD, 

DEVICE 

BYTE, 

UNIT 

BYTE, 

DEV$UNIT 

WORD, 

INIT$I0 

WORD, 

FINISH$I0 

WORD, 

QUEUE$I0 

WORD, 

CANCEL$I0 

WORD, 

DEVICE$INF0$P 

POINTER 

UNIT$INF0$P 

POINTER 

UPDATE $TIME0UT WORD, 

NUM$ BUFFERS 

WORD, 

PRIORITY 

BYTE); 


where: 

BYTE array specifying the name of the DUIB. This 
name uniquely identifies the device-unit to the I/O 
System. If you are an iRMX 86 user, you specify 
this name when attaching a unit by means of the 
RQ$A$PHYSICAL$ATTACH$DEVICE system call. If you 
are an iRMX 88 user, you specify the name when 
configuring with the Interactive Configuration 
Utility. Device drivers can ignore this field. 

WORD specifying file driver validity. Setting bit 
ntimber 1 of this word Implies that file driver 
number 1+1 can attach this device-unit. Clearing 
bit number i implies that file driver i+1 cannot 
attach this device-unit. The low-order bit is bit 
0. The bits are associated with the file drivers 
as follows: 

bit file driver 


0 physical (no. 1) 

1 stream (no. 2) 

3 named (no. 4) 

The remainder of the word must be set to zero. 

(For iRMX 88 users, the physical file driver can 
attach devices which are files, and the named file 
driver can attach devices which can contain 
multiple files.) Device drivers can ignore this 
field. 


NAME 


FILE$DRIVERS 
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FUNCTS 


FLAGS 


DEV$GRAN 


BYTE specifying the I/O function validity for this 
device-unit. Setting bit number i Implies that this 
device-unit supports function number i. Clearing bit 
number i implies that the device-unit does not 
support function number i. The low-order bit is bit 
0. The bits are associated with the functions as 
follows: 

bit function 

0 F$READ 

1 F$WRITE 

2 F$SEEK 

3 F$SPECIAL 

4 F$ATTACH$DEV 

5 F$DETACH$DEV 

6 F$0PEN 

7 F$CL0SE 

Bits 4 and 5 should always be set. Every device 
driver requires these functions. 

This field is used for informational purposes only. 
The setting or clearing of bits in this field does 
not limit the device driver from performing any I/O 
function. In fact, each device driver must be able 
to support all of the I/O functions, either by per- 
forming the function or by returning a condition code 
indicating the inability of the device to perform 
that function. However, in order to provide accurate 
status Information, this field should indicate the 
device’s ability to perform the I/O functions. 

BYTE specifying characteristics of diskette devices. 
The significance of the bits is as follows: 

bit meaning 

0 0 = not a diskette device; 

1 = diskette device 

1 0 = single density; 1 = double density 

2 0 “ single sided; 1 = double sided 

3 0 = 8-inch diskettes; 

1 “ 5 1/4-inch diskettes 
4-7 reserved 

For non-diskette devices, bits 1-7 of this field have 
no significance. 

WORD specifying the device granularity in bytes. 

This parameter is most important for random access 
devices. It specifies the minimum number of bytes of 
information that the device reads or writes in one 
operation. You should set this value equal to the 
volume granularity specified when the volume was 
formatted. 
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LOW$DEV$SIZE 

HIGH$DEV$SIZE 

DEVICE 

UNIT 

DEV$UNIT 

INIT$IO 

FINISH$IO 

QUEUE$IO 

CANCEL$IO 

DEVICE$INFO$P 

UNIT$INFO$P 

UPDATE$TIMEOUT 


WORD pair that forms a 32-bit field specifying the 
number of bytes of Information that the device-unit 
can store. 

BYTE specifying the device number of the device with 
which this device-unit is associated. Device drivers 
can ignore this field. 

BYTE specifying the unit number of this device-unit. 
This distinguishes the unit from the other units of 
the device. 

WORD specifying the device-unit number. This number 
distinguishes the device-unit from the other units in 
the entire hardware system. Device drivers can 
ignore this field. 

WORD specifying the offset in the code segment of 
this unit’s Initialize I/O device driver procedure. 

WORD specifying the offset in the code segment of 
this unit’s Finish I/O device driver procedure. 

WORD specifying the offset in the code segment of 
this unit’s Queue I/O device driver procedure. 

WORD specifying the offset in the code segment of 
this unit’s Cancel I/O device driver procedure. 

POINTER to a structure which contains additional 
information about the device. The common and random 
access device drivers require device information 
structures of a particular format. These structures 
are described in Chapter 4. If you are writing a 
custom driver, you can place information in this 
structure depending on the needs of your driver. 
Specify a zero for this parameter if the associated 
device driver does not use this field. 

POINTER to a structure that contains additional 
information about the unit. Random access device 
drivers require this unit information structure in a 
particular format. Refer to Chapter 4 for further 
information. If you are writing a custom device 
driver, place information in this structure depending 
on the needs of your driver. Specify a zero for this 
parameter if the associated device driver does not 
use this field. 

WORD specifying the number of system time units that 
the I/O System is to wait before writing a partial 
sector after processing a write request for a disk 
device. In the case of drivers for non-disk devices, 
this field should be set to OFFFFH during 
configuration. Device drivers can ignore this field. 
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NUM$BUFFERS WORD which, if not zero, specifies that the device 

is of the random access variety and indicates the 
number of buffers I/O System may allocate. The I/O 
System uses these buffers to perform data blocking 
and deblocking operations. That is, it guarantees 
that data is read or written beginning on sector 
boundaries. If you desire, the random access 
support routines can also be made to guarantee that 
no data is written or read across track boundaries 
in a single request (see the section on the unit 
information table in Chapter 4). A value of zero 
indicates that the device is not a random access 
device. Device drivers can ignore this field. 

PRIORITY BYTE specifying the priority of the I/O System 

service task for the device. Device drivers can 
ignore this field. 


Using the DUIBs 

In order to use the I/O System to connect your application software and 
any files on a device-unit, the unit must first be attached. If you are 
an iRMX 88 user, this is done automatically when you first attach or 
create a file on the unit. If you are an iRMX 86 user, you attach the 
unit by using the RQ$A$PHYSICAL$ATTACH$DEVICE system call (refer to the 
iRMX 86 SYSTEM PROGRAMMER’S REFERENCE MANUAL for a description of this 
system call). 

When you cause a unit to become attached, the I/O System assumes that the 
device-unit identified by the device name field of the DUIB has the 
characteristics identified in the remainder of the DUIB. Thus, whenever 
the application software makes any I/O requests using the connection to 
the attached device-unit, the I/O System ascertains the characteristics 
of that unit, including which device driver procedures to call in order 
to actually process the I/O request, by means of the associated DUIB. 

The I/O System looks at the DUIB and calls the appropriate device driver 
routine listed there in order to process the I/O request. 

If you would like the I/O System to assume different characteristics at 
different times for a particular device-unit, you can accomplish this by 
providing alternate DUIBs for the device-unit. If you supply multiple 
DUIBs, each containing identical device number, unit number, and 
device-unit number parameters, but different DUIB device name parameters, 
you can choose which DUIB to associate with a device-unit that you are 
attaching by specifying the appropriate dev$name parameter in the 
RQ$A$PHYSICAL$ATTACH$DEVICE system call (for iRMX 86 users) or the 
appropriate device name when calling DQ$ATTACH$FILE or DQ$CREATE$FILE 
(for iRMX 88 users). Before the DUIBs for a unit can be changed, 
however, the unit must be detached. 
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Figure 2-1 illustrates this concept. It shows six DUIBs, two for each of 
three units of one device. The main difference within each pair of DUIBs 
in this figure is the device granularity parameter, which is either 128 
or 512. With this setup, a user can attach any unit of this device with 
one of two device granularities. In Figure 2-1, units 0 and 1 are 
attached with a granularity of 128 and unit 2 with a granularity of 512. 
To change this, the user can detach the device and attach it again using 
the other DUIB name. 


name = UNITA 


name = UNITA1 

\ 

devSgran = 128 


dev$gran = 512 

1 

device = 1 


device = 1 


unit = 0 


unit = 0 

1 

dev$unlt = 6 


dev$unlt = 6 

) 


I 


DUIBs for 
device-unit 6 


CALL RQ$A$PHYSICAL$ATTACH$DEVICE (UNITA,...) 


name - UNITS 
dev$gran = 128 


device = 1 
unit = 1 
dev$unit = 7 


name = UNITB1 
devSgran = 512 


device = 1 
unit = 1 
dev$unit = 7 


DUIBs for 
device-unit 7 


CALL RQ$PHYStCAL$ATTACH$DEVICE (UNITS,.. ) 


name = UNITC 


name = UNITC1 

\ 

devSgran = 128 


devSgran = 512 

1 

device = 1 


device = 1 


unit = 2 


unit = 2 

1 

dev$unlt = 8 


dev$unlt = 8 

) 


DUIBs for 
device-unit 8 


CALL RA$A$PHYSICAL$ATTACH$DEVICE (UNITC1,...) 


Figure 2-1, Attaching Devices 


Creating DUIBs 

Before the system starts running, you must provide all of the DUIBs that 
your system will ever need; you cannot create additional ones at run 
time. If you are an iRMX 88 user, you define your DUIBs during 
Interactive configuration. If, on the other hand, you are an iRMX 86 
user, place the DUIBs in the I/O System configuration file as a part of 
the I/O System configuration process. The iRMX 86 CONFIGURATION GUIDE 
describes this procedure. Observe the following guidelines when creating 
DUIBs: 


• Specify a unique name for every DUIB, even those that describe 
the same device-unit. 

• Create at least one DUIB for every device-unit in the hardware 
configuration. Since the DUIB contains the addresses of the 
device driver routines, this guarantees that no device-unit is 
left without a device driver to handle its I/O. 
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• Make sure to specify the same device driver procedures in all of 
the DUIBs associated with a particular device. There is only one 
set of device driver routines for a given device, and each DUIB 
for that device must specify this unique set of routines. 

• If you are using a common or random access device driver, you 
must create a device information table for each device. If you 
are using a random access device driver, you must create a unit 
information table for each unit. See Chapter 4 for 
specifications of these tables. Place pointers to these tables 
in the device$info$p and unit$info$p fields of the appropriate 
DUIBs. If you are using custom device drivers and they require 
these or similar tables, you must create them, as well. 


I/O REQUEST/RESULT SEGMENT (lORS) 

An I/O request/result segment (lORS) is a data structure that the I/O 
System creates when a user requests an I/O operation. It contains 
information about the request and about the unit on which the operation 
is to be performed. The I/O System passes the lORS to the appropriate 
device driver which then processes the request. When the device driver 
performs the operation indicated in the lORS, it must modify the lORS to 
indicate what it has done and send the lORS back to the response mailbox 
(exchange) Indicated in the lORS. 

The lORS is the only mechanism that the I/O System uses to transmit 
requests to device drivers. Its structure is always the same. Every 
device driver must be aware of this structure and must update the 
information in the lORS after performing the requested function. The 
lORS is structured as follows: 

DECLARE 

lORS STRUCTURE ( 


STATUS 

WORD, 

UNIT$STATUS 

WORD, 

ACTUAL 

WORD, 

ACTUAL$FILL 

WORD, 

DEVICE 

WORD, 

UNIT 

BYTE, 

FUNCT 

BYTE, 

SUBFUNCT 

WORD, 

LOW$DEV$LOC 

WORD, 

HIGH$DEV$LOC 

WORD, 

BUFF$P 

POINTER 

COUNT 

WORD, 

COUNT$FILL 

WORD, 

AUX$P 

POINTER 

LINK$FOR 

POINTER; 

LINK$BACK 

POINTER 

RESP$MBOX 

WORD, 

DONE 

BYTE, 

FILL 

BYTE, 

CANCEL$ID 

WORD) ; 
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where: 

STATUS 

UNIT$ STATUS 


ACTUAL 

ACTUAL$FILL 

DEVICE 

UNIT 

FUNCT 


WORD In which the device driver must place the 
condition code for the I/O operation* The E$OK 
condition code indicates successful completion of the 
operation* For a complete list of possible condition 
codes, see either the iRMX 86 NUCLEUS REFERENCE 
MANUAL, the iRMX 86 BASIC I/O SYSTEM REFERENCE MANUAL, 
and the iRMX 86 EXTENDED I/O SYSTEM REFERENCE MANUAL, 
or the iRMX 88 REFERENCE MANUAL* 

WORD in which the device driver must place additional 
status information if the status parameter was set to 
indicate the E$IO condition* The unit status codes 
and their descriptions are as follows: 


code 

mnemonic 

description 

0 

IO$UNCLASS 

Unclassified error 

1 

10$ SOFT 

Soft error; a retry is possible 

2 

I0$HARD 

Hard error; a retry is impossible 

3 

I0$0PRINT 

Operator intervention is required 

4 

I0$WRPR0T 

Write-protected volume 


The I/O System reserves values 0 through 15 (the 
rightmost four bits) of this field for unit status 
codes* The high 12 bits of this field can be used for 
any other purpose that you wish* For example, the 
ISBC 204 driver places the result byte in the high 
eight bits of this field- Refer to the iSBC 204 
FLEXIBLE DISKETTE CONTROLLER HARDWARE REFERENCE MANUAL 
for further information on the result byte* 

WORD which the device driver must update on the 
completion of an I/O operation to Indicate the number 
of bytes of data actually transferred* 

Reserved WORD* 

WORD in which the I/O System places the number of the 
device for which this request is intended* 

BYTE in which the I/O System places the number of the 
unit for which this request is intended* 

BYTE in which the I/O System places the function code 
for the operation to be performed* Possible function 
codes are: 
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SUBFUNCT 


LOW$DEV$LOC 

HIGH$DEV$LOC 


BUFF$P 

COUNT 

COUNT$FILL 

AUX$P 


function code 

F$READ 0 

F$WRITE 1 

F$SEEK 2 

F$SPECIAL 3 

F$ATTACH$DEV 4 

F$DETACH$DEV 5 

F$OPEN 6 

F$CLOSE 7 


WORD in which the I/O System places the actual 
function code of the operation, when the F$SPECIAL 
function code was placed in the FUNCT field. The 
value in this field depends on the device driver. 
The random access device driver currently supports 
the following two special functions: 


function code 

FORMAT/QUERY 0 

SATISY 1 

NOTIFY 2 


To maintain compatibility with random access device 
drivers and to allow for future expansion, other 
drivers should avoid using these codes, and 3 through 
10 as well, for other functions. 

WORD pair that forms a 32-blt field in which the I/O 
System places the absolute byte location on the I/O 
device where the operation is to be performed. For 
example, for the F$WRITE operation, this is the 
address on the device where writing begins. If a 
random access device driver is used and the 
track$slze field in the unit’s unit information table 
contains a value greater than zero, this field 
contains the track number (in HIGH$DEV$L0C) and 
sector number (in L0W$DEV$L0C ) . If track$slze 
contains zero, this field contains a 32-bit sector 
number. 

POINTER which the I/O System sets to indicate the 
internal buffer where data is read from or written to. 

WORD which the I/O System sets to indicate the number 
of bytes to transfer. 

Reserved WORD. 

POINTER which the I/O System sets to indicate the 
location of auxiliary data. This data is used when 
the request calls the F$SPECIAL function, in order to 
pass a variety of kinds of special function data. 

For example, to format a track on a hard disk, set 
FUNCT equal to F$SPECIAL, set SUBFUNCT equal to 0, 
and set AUX$P to point to a structure of the form: 
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LINK$FOR 


LINK$BACK 


RESP$MBOX 


DONE 


FILL 


DECLARE 

FORMAT$TRACK STRUCTURE( 

TRACK$NUMBER WORD, 

INTERLEAVE WORD, 

TRACK$OFFSET WORD, 

FILL$CHAR WORD) ; 

The other Intel-defined F$SPECIAL options do not have 
predefined structures. 

POINTER that the device driver can use to implement a 
request queue. Random access and common drivers use 
this field to point to the location of the next lORS 
in the queue. 

POINTER that the device driver can use to implement a 
request queue. Random access and common drivers use 
this field to point to the location of the previous 
lORS in the queue. 

WORD that the I/O System fills with either an iRMX 86 
token for the response mailbox or the address of an 
iRMX 88 exchange. Upon completion of the I/O 
request, the device driver must send the lORS to this 
response mailbox or exchange. 

BYTE that the device driver can set to TRUE (OFFH) or 
FALSE (OOH) to indicate whether or not the entire 
request has been completed. Random access and common 
drivers use this byte in this fashion. 

Reserved BYTE. 


CANCEL$ID WORD used to identify queued I/O requests that are to 

be removed from the queue by the CANCEL$IO procedure. 


DEVICE INTERFACES 


One or more of the routines in every device driver must actually send 
commands to the device Itself in order to carry out I/O requests. The 
steps that a procedure of this sort must go through vary considerably, 
depending on the type of I/O device. Procedures supplied with the I/O 
System to manipulate devices such as the ISBC 204 and iSBC 206 devices 
use the PL/M-86 bulltlns INPUT and OUTPUT to transmit to and receive from 
I/O ports. Other devices may require different methods. The I/O System 
places no restrictions on the method of communicating with devices. Use 
the method that the device requires. 
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There are three types of device drivers in the iRMX 86 and iRMX 88 
environments: common, random access, and custom. This chapter defines 

the distinctions between the types of drivers and discusses the 
characteristics and data structures pertaining to common and random 
access device drivers. Chapters 5 and 6 are devoted to explaining how to 
write the various types of device drivers. 


CATEGORIES OF DEVICES 


Because the I/O Systems provide procedures that constitute the bulk of 
any common or random access device driver, you should consider the 
possibility that your device is a common or random access device. If 
your device falls in either of these categories, you can avoid most of 
the work of writing a device driver by using the supplied procedures. 
The following sections define the three types of devices. 


COMMON DEVICES 

Common devices are relatively simple devices, such as line printers, that 
conform to the following conditions: 

• A first-in/first-out mechanism for queuing requests is sufficient 
for accessing these devices. 

• Only one interrupt level is needed to service a device. 

• Data either read or written by these devices does not need to be 
broken up into blocks. 

If you have devices that fit into this category, you can save the effort 
of creating an entire device driver by using the common driver routines 
supplied by the I/O System. Chapter 5 of this manual describes the 
procedures that you must write to complete the balance of a common device 
driver. 


RANDOM ACCESS DEVICES 

A random access device is a device, such as a disk drive, in which data 
can be read from or written to any address of the device. The support 
routines provided by the I/O System for random access assume the 
following conditions: 
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• A f irst-in/f Irst-out mechanism for queuing requests is sufficient 
for accessing these devices. 

• Only one Interrupt level is needed to service the device. 

• I/O requests must be broken up into blocks of a specific length. 

• The device supports random access seek operations. 

If you have devices that fit into the random access category, you can 
take advantage of the random access support routines provided by the I/O 
System. Chapter 5 of this manual describes the procedures that you must 
write to conq>lete the balance of a random access device driver. 


CUSTOM DEVICES 

If your device fits neither the common nor the random access category, 
you must write the entire driver for the device. The requirements of a 
custom device driver are defined in Chapter 6. 


I/O SYSTEM-SUPPLIED ROUTINES FOR COMMON AND RANDOM ACCESS DEVICE DRIVERS 


The I/O System supplies the common and random access routines that the 
I/O System calls when processing I/O requests. Flow charts for these 
procedures can be found in Appendix A; their names and functions are as 
f ollows : 


Common Routine Random Access Routine Function 


INIT$IO 


FINISH$IO 


QUEUE$IO 

CANCEL$IO 


RAD$INIT$IO 


RAD$FINISH$IO 


RAD$QUEUE$IO 

RAD$CANCEL$IO 


Creates the resources needed by 
the remainder of the driver 
routines, creates an Interrupt 
task, and calls a user-supplied 
routine that initializes the 
device itself. 

Deletes the resources used by 
the other driver routines, 
deletes the interrupt task, and 
calls a user-supplied procedure 
that performs final processing 
on the device itself. 

Places I/O requests (lORSs) on 
the queue of requests. 

Removes one or more requests 
from the request queue, possibly 
stopping the processing of a 
request that has already been 
started. 
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In addition to these routines, the I/O Systems supply an interrupt 
handler (interrupt service routine) and either INTERRUPT$TASK or 
RAD$INTE^UPT$TASK, which respond to all interrupts generated by the 
units of a device, process those interrupts, and start the device working 
on the next I/O request on the queue* This interrupt task is the one 
that the INIT$IO or RAD$INIT$IO procedure creates. 

After a device finishes processing a request, it sends an interrupt to 
the processor. As a consequence, the processor calls the interrupt 
handler* This handler either processes the interrupt Itself or Invokes 
an Interrupt task to process the interrupt. Since an Interrupt handler 
is limited in the types of system calls that it can make and the number 
of interrupts that can be enabled while it is processing, an interrupt 
task usually services the interrupt. The interrupt task feeds the 
results of the Interrupt back to the I/O System (data from a read 
operation, status from other types of operations). The interrupt task 
then gets the next I/O request from the queue and starts the device 
processing this request. This cycle continues until the device is 
detached. 

Figure 3-1 shows the interaction between an Interrupt task, an I/O 
device, an I/O request queue, and a Qneue I/O device driver procedure* 

The interrupt task in this figure is in a continual cycle of waiting for 
an interrupt, processing it, getting the next I/O request, and starting 
up the device again* While this is going on, the Queue I/O procedure 
runs in parallel, putting additional I/O requests on the queue. 


REQUEST QUEUE 


INTERRUPT TASK 



Figure 3-1. Interrupt Task Interaction 
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I/O SYSTEM ALGORITHM FOR CALLING THE DEVICE DRIVER PROCEDURES 


The I/O System calls each of the four device driver procedures In 
response to specific conditions. Figure 3-2 Is a flow chart that 
Illustrates the conditions under which three of the four procedures are 
called. The following numbered paragraphs discuss the portions of Figure 
3-2 labelled with corresponding circled numbers. 

1. In order to start I/O processing, an application task must make 
an I/O request. This can be done by making any of a variety of 
system calls. However, If you are an IRMX 86 user, the first I/O 
request to each device-unit must be an 

RQ$A$PHYSICAL$ATTACH$DEVICE system call, and If you are an IRMX 
88 user, the first request to each device-unit must be either a 
DQ$ATTACH or a DQ$CREATE system call. 

2. If the request results from an RQ$A$PHYSICAL$ATTACH$DEVICE, a 
DQ$ATTACH, or a DQ$CREATE system call, the I/O System checks to 
see If any other units of the device are currently attached. If 
no other units of the device are currently attached, the I/O 
System realizes that the device has not been Initialized and 
calls the Initialize I/O procedure first, before queueing the 
request. 

3. Whether or not the I/O System called the Initialize I/O 
procedure. It calls the Queue I/O procedure to queue the request 
for execution. 

4. If the request just queued resulted from an 
RQ$A$PHYSICAL$DETACH$DEVICE system call, the I/O System checks to 
see If any other units of the device are currently attached. If 
no other units of the device are attached, the I/O System calls 
the Finish I/O procedure to do any final processing on the device 
and clean up resources used by the device driver routines. 

The IRMX 86 I/O System calls the fourth device driver procedure, the 
Cancel I/O procedure, under the following conditions: 

• If the user makes an RQ$A$PHYSICAL$DETACH$DEVICE system call 
specifying the hard detach option. In order to forclbJ^y detach 
the connection objects associated with a device-unit. The 
IRMX 86 SYSTEM PROGRAMMER'S REFERENCE MANUAL describes the hard 
detach option. 

• If the job containing the task which made a request Is deleted. 
The IRMX 88 I/O System does not call the Cancel I/O procedure. 
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© 


Figure 3- 


O The user makes an I/O request 
via a system call 



2. How the I/O System Calls the Device Driver Procedures 
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REQUIRED DATA STRUCTURES 

In order for the I/O System-supplied routines to be able to call the 
user-supplied routines, you must Include the addresses of these 
user-supplied routines, along with other Information, in a device 
information table* In addition, processing I/O requests through a random 
access driver requires a unit information table* Each device-unit 
information block (DUIB) contains one pointer field for a device 
information table and another for a unit information table* 

DUIBs which correspond to units of the same device should point to the 
same device information table, but they can point to different unit 
information tables, if the units have different characteristics* Figure 
3-3 illustrates this* 



Figure 3-3* DUIBs, Device and Unit Information Tables 
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DEVICE INFORMATION TABLE 

Common and random access device information tables contain the same 
fields in the same order, but the tables have different names. Common 
drivers refer to the device information table as COMMON$DEVICE$INFO, 
while random access drivers refer to RAD$DEVICE$INFO. For brevity, we 
show only the declaration of COMMON$DEVICE$INFO. 

DECLARE 

COMMON$DEVICE$INFO STRUCTURE( 

LEVEL WORD, 

PRIORITY BYTE, 

STACK$SIZE WORD, 

DATA$SIZE WORD, 

NUM$UNITS WORD, 

DEVICE$INIT WORD, 

DEVICE$FINISH WORD, 

DEVICE$START WORD, 

DEVICE$STOP WORD, 

DEVICE$ INTERRUPT WORD); 


where: 

LEVEL WORD specifying an encoded interrupt level at which 

the device will interrupt. The interrupt task uses 
this value in order to associate itself with the 
correct interrupt level. The values for this field 
are encoded as follows: 

Bits Value 

15-7 0 

6-4 First digit of the interrupt level (0-7) 

3 If one, the level is a master level and 

bits 6-4 specify the entire level 
number. 

If zero, the level is a slave level and 
bits 2-0 specify the second digit. 

2-0 Second digit of the interrupt level 

(0-7), if bit 3 is zero. 

NOTE 

In IRMX 88 systems, only master 
levels are available. 
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PRIORITY 


STACK$SIZE 


DATA$SIZE 


NUM$ UNITS 


DEVICE$INIT 


DEVICE$FINISH 


DEVICE $START 


DEVICE$STOP 


DEVICE $INTERRUPT 


BYTE specifying the initial priority of the 
interrupt task. The actual priority of an 
IRMX 86 interrupt task might change because the 
iRMX 86 Nucleus adjusts an interrupt task’s 
priority according to the Interrupt level that it 
services. Refer to the iRMX 86 NUCLEUS REFERENCE 
MANUAL for further Information about this 
relationship between interrupt task priorities 
and interrupt levels. 

WORD specifying the size, in bytes, of the stack 
for the user-written device interrupt procedure 
(and procedures that it calls). This number 
should not include stack requirements for the I/O 
System-supplied procedures. They add their 
requirements to this figure. 

WORD specifying the size, in bytes, of the user 
portion of the device’s data storage area. This 
figure should not Include the amount needed by 
the I/O System-supplied procedures; rather, it 
should include only that amount needed by the 
user-written routines. This then is the size of 
the read or write buffers plus any flags that the 
user-written routines need. 

WORD specifying the number of units supported by 
the driver. Units are assumed to be numbered 
consecutively, starting with zero. 

WORD specifying the start address of a 
user-written device initialization procedure. 

The format of this procedure, which is called by 
INIT$IO, is described in Chapter 5. 

WORD specifying the start address of a 
user-written device finish procedure. The format 
of this procedure, which is called by FINISH$IO, 
is described in Chapter 5. 

WORD specifying the start address of a 
user-written device start procedure. The format 
of this procedure, which is called by QUEUE$IO 
and INTERRUPT$TASK, is described in Chapter 5. 

WORD specifying the start address of a 
user-written device stop procedure. The format 
of this procedure, which is called by CANCEL$IO, 
is described in Chapter 5. 

WORD specifying the start address of a 
user-written device interrupt procedure. The 
format of this procedure, which is called by 
INTERRUPT$TASK, is described in Chapter 5. 
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Depending on the requirements of your device, you can append additional 
information to the COMMON$DEVICE$INFO or RAD$DEVICE$INFO structure. For 
example, most devices require that the I/O port address be appended to 
this structure, in order that the user-written procedures have access to 
the device. 

You must create device information tables as a part of the I/O System 
configuration process. The iRMX 86 CONFIGURATION GUIDE describes this 
procedure for iRMX 86 users. You configure IRMX 88 applications 
interactively with the Interactive Configuration Utility. 


UNIT INFORMATION TABLE 


If you have random access device drivers in your system, you must create a 
unit information table for each different type of unit in your system. 

Each random access device-unit’s DUIB must point to one unit information 
table, although multiple DUIBs can point to the same unit information 
table. The structure of the unit information table is as follows: 


DECLARE 

RAD$UNIT$INFO 

TRACK$SIZE 

MAX$RETRY 

RESERVED 


STRUCTURE ( 
WORD, 
WORD, 
WORD) ; 


where: 

TRACK$SIZE WORD specifying the size, in bytes, of a single track 
of a volume on the unit. If the device controller 
supports reading and writing across track boundaries, 
place a zero in this field. If you specify a zero for 
this field, the I/O System-supplied procedures place a 
32-bit sector number in the HIGH$DEV$LOC and 
LOW$DEV$LOC fields of the lORS. If you specify a 
nonzero value for this field, the I/O System-supplied 
procedures guarantee that read and write requests do 
not cross track boundaries. They do this by placing 
the sector number in the low order word of the 
LOW$DEV$LOC field of the lORS and the track number in 
the HIGH$DEV$LOC field before calling a user-written 
device start procedure. Instructions for writing a 
device start procedure are contained in Chapter 5. 

MAX$RETRY WORD specifying the maximum number of times an I/O 

request should be tried if an error occurs. A value of 
nine is recommended for this field. When this field 
contains a nonzero value, the I/O System-supplied 
procedures guarantee that read or write requests are 
retried if the user-supplied device start or device 
interrupt procedures return an IO$SOFT condition in the 
IORS.UNIT$ STATUS field. (The I ORS.UNIT$ STATUS field is 
described in the "lORS Structure" section of Chapter 2.) 

RESERVED Reserved WORD. 
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RELATIONSHIPS BETWEEN I/O PROCEDURES AND I/O DATA STRUCTURES 

This section brings together several of the procedures and data structures 
that have been described so far in this manual. Figure 3-4 shows the many 
relationships that exist among these entities, with solid arrows indicating 
procedure calls and dotted arrows indicating pointers. Note that the I/O 
System contains the address of each DUIB, which in turn contains the 
addresses of the procedures that the I/O System calls in order to perform 
I/O on the associated device— unit. The DUIB also has the address of the 
device information table and, if the device is a random access device, the 
unit information table. The device information table, in turn, contains 
the addresses of the procedures that are called by the procedures that the 
I/O System calls. It is through these links that the appropriate calls are 
made in the servicing of an I/O request for a particular device-unit. 



\ 

\ 

'y UNIT INFO. TABLE 


Figure 3-4. Relationships Between I/O Procedures and I/O Data Structures 
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WRITING DRIVERS FOR USE WITH BOTH IRMX 86- AND IRMX 88-BASED SYSTEMS 


A common or random access device driver that makes no system calls will be 
compatible with both the iRMX 86 and iRMX 88 I/O Systems- Consequently, 
such a device driver can be "ported" between applications based on the two 
iRMX systems. 


DEVICE DATA STORAGE AREA 


The common and random access device drivers are set up so that all data 
which is local to a device is maintained in an area of memory. The 
Initialize I/O procedure creates this device data storage area and the 
other procedures of the driver access and update information in it as 
needed. Two purposes are served by storing the device-local data in a 
central area. 

First, all device driver procedures which service individual units of the 
device can access and update the same data. The Initialize I/O procedure 
passes the address of the area back to the I/O System, which in turn gives 

the address to the other procedures of the driver. They can then place 

information relevant to the device as a whole into the area. The identity 
of the first lORS on the request queue is maintained in this area, as well 

as the attachment status of the individual units and a means of accessing 

the interrupt task. 

Second, several devices of the same type can share the same device driver 
code and still maintain separate device data areas. For example, suppose 
two iSBC 204 devices use the same device driver code. The same Initialize 
I/O procedure is called for each device, and each time it is called it 
obtains memory for the device data. However, the memory areas that it 
creates are different. Only the incarnations of the routines that service 
units of a particular device are able to access the device data area for 
that device. 

Although the common and random access device drivers already provide this 
mechanism, you may want to include a device data storage area in any custom 
driver that you write. 
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This chapter contains two kinds of information that writers of device 
drivers will find useful. Presented first are summaries of the actions 
that the I/O System takes in response to the various kinds of I/O 

requests that application tasks can make. Next are three tables one 

for each type of device driver that show which DUIB and lORS fields 

device drivers should be concerned with. 


I/O SYSTEM RESPONSES TO I/O REQUESTS 

This section shows which device driver procedures the I/O System calls 
when it processes each of the eight kinds of I/O requests. When there 
are multiple calls, the order of the calls is significant. 


ATTACH DEVICE REQUESTS 

When the I/O System receives the first attach device request for a 
device, it makes the following calls to device driver procedures in the 
following order: 

The Call The Effects of the Call 

Initialize I/O The driver resets the device as a whole 

and creates the device data storage 
area and interrupt tasks. 

Queue I/O, with the The driver resets the selected unit. 

FUNCT field of the lORS 
set to F$ATTACH (=4) 

When the I/O System receives an attach device request that is not the 
first for the device, it makes the following call: 

The Call The Effects of the Call 

Queue I/O, with the The driver resets the selected unit. 

FUNCT field of the lORS 
set to F$ATTACH (=4) 


DETACH DEVICE REQUESTS 

When the I/O System receives a detach device request, and there is more 
than one unit of the device attached, it makes the following call: 

The Call The Effects of the Call 

Queue I/O, with the The driver performs cleanup operations 

FUNCT field of the lORS for the selected unit, if necessary, 

set to F$DETACH (=5) 
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When the I/O System receives a detach device request, and there is only 
one attached unit on the device, it makes the following calls to device 
driver procedures in the following order: 


The Call 


Queue I/O, with 

the 

The 

FUNCT field of the lORS 

for 

set to F$DETACH 

(-5) 


Finish I/O 


The 



for 


The Effects of the Call 
driver performs cleanup operations 
the selected unit, if necessary. 

driver performs cleanup operations 
the device as a whole, if necessary. 


READ, WRITE, OPEN, CLOSE, SEEK, AND SPECIAL REQUESTS 

When the I/O System receives a read, write, open, close, seek, or special 
request, it makes the following call to a device driver procedure: 


The Call 

Queue I/O, with the FUNCT 
field of the lORS set to 
F$READ (-0), F$WRITE (-1), 
F$0PEN (=6), F$CL0SE (-7), 
F$SEEK (-2), or F$SPECIAL 
(*3), depending on the type 
of the I/O request. 


The Effects of the Call 
The driver performs the requested 
operation. (F$0PEN and F$CL0SE 
usually require no processing.) 


CANCEL REQUESTS 


When a connection is deleted while I/O might be in progress, such as when 
an iRMX 86 job is deleted, the I/O System makes the following calls to 
device driver procedures in the follcwlng order: 


The Call 
Cancel I/O. 


Queue I/O, with the 
FUNCT field of the 
lORS set to F$CL0SE 
(-7) 


The Effects of the Call 
The driver removes from the request queue 
all requests that contain the same Cancel ID 
value as that in the current request, and 
stops processing if necessary. 

When this request reaches the front of the 
queue. It Is simply returned to the indicated 
response mailbox (exchange). 


DUIB AND lORS FIELDS USED BY DEVICE DRIVERS 


The following tables Indicate, for each type of device driver, the fields 
of DUIBs and lORSs with which user-written portions of device drivers 
need to be concerned. 
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Table 4-1, DUIB and lORS Fields Used by Common Device Drivers 


Attach Detach 

Device Device Open Close Read Write Seek Special 



r — ” is read by the device driver 

1 is written by the device driver 

1 might be read by some device drivers 


-3 










I/O REQUESTS 


Table 4-2. DUIB and lORS Fields Used by Random Access Device Drivers 


Attach Detach 

Device Device Open Close Read Write Seek Special 


File$drivers 

Functs 


Dev$gran 

Dev$size 

Device 


m 

m 

m 

m 

m 

m 

m 

m 

m 

m 

m 

m 

m 

m 


Dev$unit 

Init$io 

Flnish$io 

Queue$io 

Cancel$io 

Device$info$p 

Unit$info$p 

Update$tlmeout 

Num$buffers 

Priority 

ORS 
Status 
Unit$status 
Actual 
Actual$f ill 
Device 
it 

Funct 
Subfunct 
Low$dev$loc 
Hlgh$dev$loc 
Buff$p 
Count 

Count$f ill 
x$p 

Link$f or 
Link$back 
Resp$mbox 
Done 
Fill 

Cancel$id 


‘ is read by the device driver 

r is written by the device driver 

I might be read by some device drivers 
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Table 4-3. DUIB and lORS Fields Used by Custom Device Drivers 


Attach Detach 

Device Device Open Close Read Write Seek Special 



— is read by the device driver 

■“ is written by the device driver 

— might be read by some device drivers 

— is available for any purpose suiting the needs of the device 
driver 
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CHAPTER 5. WRITING COMMON OR RANDOM ACCESS DEVICE DRIVERS 


This chapter contains the calling sequences for the procedures that you 
must provide when writing a common or random access device driver. Where 
possible, descriptions of the duties of these procedures accompany the 
calling sequences. 

The I/O System-supplied procedures are referred to in this chapter, for 
brevity, as if the chapter were written only for writers of common device 
drivers. For example, *'INIT$IO" is shorthand for "INIT$IO or 
RAD$INIT$IO". 


GENERAL INFORMATION 


The routines that are provided by the I/O System and that the I/O System 
calls comprise the bulk of a common or random access a device driver. 
These routines, in turn, make calls to device-dependent routines that you 
must supply. These device-dependent routines are described here briefly 
and then are presented in detail: 

A device initialization procedure. This procedure must perform any 
initialization functions necessary to get the device ready to process 
I/O. INIT$IO calls this procedure. 

A device finish procedure. This procedure must perform any 
necessary final processing on the device so that the device can be 
detached. FINISH$IO calls this procedure. 

A device start procedure. This procedure must start the device 
processing any possible I/O function. QUEUE$IO and INTERRUPT $TASK 
(the I/O System-supplied interrupt task) call this procedure. 

A device stop procedure. This procedure must stop the device from 
processing the current I/O function, if that function could take an 
indefinite amount of tlme^^ GANCEL$IO calls this procedure. 

A device interrupt procedure This procedure must do all of the 
device-dependent processing that results from the device sending an 
interrupt. INTERRUPT$TASK calls this procedure. 


DEVICE INITIALIZATION PROCEDURE 


The INIT$IO procedure calls the user-written device initialization 
procedure in order to initialize the device. The format of the call to 
the user-written device initialization procedure is as follows: 

CALL devlce$inlt(duib$p, ddata$p, status$p); 
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where; 

devlce$init Name of the device initialization procedure. You can 
use any name for this procedure, as long as it doesn’t 
conflict with other procedure names and you include 
the name in the device information table. 

duib$p POINTER to the DUIB of the device-unit being 

attached. From this DUIB, the device initialization 
procedure can obtain the device information table, 
where information such as the I/O port address is 
stored. 

ddata$p POINTER to the user portion of the device's data 

storage area. You must specify the size of this 
portion in the device information table for this 
device. The device initialization procedure can use 
this data area for whatever purposes it chooses. 
Possible uses for this data area include local flags 
and buffer areas. 

status$p POINTER to a WORD in which the device initialization 

procedure must return the status of the initialization 
operation. It should return the E$OK condition code 
if the initialization is successful; otherwise it 
should return the appropriate exceptional condition 
code. If initialization does not complete 
successfully, the device Initialization procedure must 
ensure that any data areas it Initializes are reset. 

If you have a device that does not need to be initialized before it can 
be used, you can use the default device initialization procedure supplied 
by the I/O System. The name of this procedure is DEFAULT$INIT. Specify 
this name in the device information table. DEFAULT$INIT does nothing but 
return the E$OK condition code. 


DEVICE FINISH PROCEDURE 

The FINISH$IO procedure calls the user-written device finish procedure in 
order to perform final processing on the device, after the last I/O 
request has been processed. The format of the call to the device finish 
procedure is as follows: 

CALL device$f inish(duib$p, ddata$p); 


where: 

device$f Inish Name of the device finish procedure. You can use any 
name for this procedure, as long as it doesn't 
conflict with other procedure names and you include 
the name in the device information table. 
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duib$p POINTER to the DUIB of the device-unit being 

detached. From this DUIB, the device finish procedure 
can obtain the device information table, where 
information such as the I/O port address is stored. 

ddata$p POINTER to the user portion of the device *s data 

storage area. The device finish procedure should 
obtain, from this data area, identification of any 
resources other user-written procedures may have 
created, and delete these resources. 

If you have a device that does not require any final processing, you can 
use the default device finish procedure supplied by the I/O System. The 
name of this procedure is DEFAULT$FINISH. Specify this name in the 
device information table. DEFAULT$FINISH merely returns to the caller 
with an E$OK condition code and is normally used when the default 
initialization procedure DEFAULT$INIT is used. 


DEVICE START PROCEDURE 

Both QUEUE$IO and INTERRUPT$TASK make calls to the device start procedure 
in order to start an I/O function. QUEUE$IO calls this procedure on 
receiving an I/O request when the request queue is empty. INTERRUPT$TASK 
calls the device start procedure after it finishes one I/O request if 
there are more I/O requests on the queue. The format of the call to the 
device start procedure is as follows; 

CALL device$start(iors$p, duib$p, ddata$p); 
where; 

device$start Name of the device start procedure. You can use any 
name for this procedure, as long as it doesn’t 
conflict with other procedure names and you Include 
the name in the device information table. 

iors$p POINTER to the lORS of the request. The device start 

procedure must access the lORS in order to obtain 
information such as the type of I/O function 
requested, the address on the device of the byte where 
I/O is to commence, and the buffer address. 

dulb$p POINTER to the DUIB of the device-unit for which the 

I/O request is intended. The device start procedure 
can use the DUIB to access the device information 
table, where information such as the I/O port address 
is stored. 

ddata$p POINTER to the user portion of the device’s data 

storage area. The device start procedure can use this 
data area to set flags or store data. 
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The device start procedure must do the following: 

• It must be able to start the device processing any of the 
functions supported by the device and recognize that requests 
for nonsupported functions are error conditions. 

• If it transfers any data, it must update the lORS. ACTUAL field 
to reflect the total number of bytes of data transferred (that 
is, if it transfers 128 bytes of data, it must put 128 in the 
lORS. ACTUAL field). 

• If an error occurs when the device start procedure tries to 
start the device (such as on an F$WRITE request to a 
write-protected disk), the device start procedure must set the 
lORS. STATUS field to indicate an E$IO condition and the 
IORS.UNIT$STATUS field to a nonzero value. The lower four bits 
of the field should be set as indicated in the ”IORS Structure" 
section of Chapter 2. The remaining bits of the field can be 
set to any value (for example, the iSBC 204 device driver 
returns the device’s result byte in the remainder of this 
field). If the function completes without an error, the device 
start procedure must set the lORS. STATUS field to indicate an 
E$0K condition. 

• If the device start procedure determines that the I/O request 
has been processed completely, either because of an error or 
because the request has been successfully conqpleted, it must set 
the lORS.DONE field to TRUE. The I/O request will not always be 
completed; it may take several calls to the device interrupt 
procedure before a request is completed. However, if the 
request is finished and the device start procedure does not set 
the lORS.DONE field to TRUE, the device driver support routines 
will wait until the device sends an Interrupt and the device 
interrupt procedure sets lORS.DONE to TRUE, before determining 
that the request is actually finished. 


DEVICE STOP PROCEDURE 

The CANCEL$I0 procedure calls the user-written device stop procedure in 
order to stop the device from performing the current I/O function. The 
format of the call to the device stop procedure is as follows: 

CALL device$stop(iors$p, duib$p, ddata$p); 


where: 

device$stop Name of the device stop procedure. You can use any 
name for this procedure, as long as it doesn't 
conflict with other procedure names and you Include 
this name in the device Information table. 
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iors$p POINTER to the lORS of the request. The device stop 

procedure needs this information to determine what 
type of function to stop. 

duib$p POINTER to the DUIB of the device-unit on which the 

I/O function is being performed. 

ddata$p POINTER to the user portion of the device’s data 

storage area. The device stop procedure can use this 
area to store data, if necessary. 

If you have a device which guarantees that all I/O requests will finish 
in an acceptable amount of time, you can omit writing a device stop 
procedure and use the default procedure supplied with the I/O System. 

The name of this procedure is DEFAULT$STOP . Specify this name in the 
device information table. DEFAULT$STOP simply returns to the caller. 


DEVICE INTERRUPT PROCEDURE 

INTERRUPT$TASK calls the user-written device interrupt procedure to 
process an Interrupt that just occurred. Whereas the device start 
procedure is called to start the device performing an I/O function, the 
device Interrupt procedure is called when the device finishes performing 
the function. The format of the call to the device interrupt procedure 
is as follows: 

CALL devlce$lnterrupt(iors$p, duib$p, ddata$p); 


where; 


device$lnterrupt Name of the device interrupt procedure. You can 

use any name for this procedure, as long as it 
doesn’t conflict with other procedure names and 
you Include this name in the device information 
table . 


lors$p POINTER to the lORS of the request being 

processed. The device interrupt procedure must 
update Information in this lORS. A value of zero 
for this parameter indicates that there are no 
requests on the request queue and that the 
interrupt is extraneous. 

dulb$p POINTER to the DUIB of the device-unit on which 

the I/O function was performed. 

ddata$p POINTER to the user portion of the device’s data 

storage area. The device interrupt procedure can 
update flags in this data area or retrieve data 
sent by the device. 


5-5 



WRITING COMMON OR RANDOM ACCESS DEVICE DRIVERS 


The device interrupt procedure must do the following: 

• It must determine whether the interrupt resulted from the 
completion of an I/O function by the correct device-unit. 

• If the correct device-unit did send the interrupt, the device 
interrupt procedure must determine whether the request is 
finished. If the request is finished, the device interrupt 
procedure must set the lORS.DONE field to TRUE. 

• It must process the interrupt. This may involve setting flags 
in the user portion of the data storage area, tranferring data 
written by the device to a buffer, or some other operation. 

• If an error has occurred, it must set the lORS. STATUS field to 
indicate an E$IO condition and the lORS .UNIT$STATUS field to a 
nonzero value. The lower four bits of the field should be set 
as Indicated in the "lORS Structure" section of Chapter 2. The 
remaining bits of the field can be set to any value (for 
example, the iSBC 204 and 206 device drivers return the device’s 
result byte in the remainder of this field). It must also set 
the lORS.DONE field to TRUE, indicating that the request is 
finished because of the error. 

• If no error has occurred, it must set the lORS. STATUS field to 
indicate an E$0K condition. 
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Custom device drivers are drivers that you create in their entirety 
because your device doesn’t fit into either the common or random access 
device category, either because the device requires a priority-ordered 
queue, multiple interrupt levels, or because of some other reasons that 
you have determined. When you write a custom device driver, you must 
provide all of the features of the driver, including creating and 
deleting resources, implementing a request queue, and creating an 
interrupt handler. You can do this in any manner that you choose as long 
as you supply the following four procedures that the I/O System can call: 

An Initialize I/O Procedure . This procedure must initialize the 
device and create any resources needed by the procedures in the 
driver. 

A Finish I/O Procedure . This procedure must perform any final 
processing on the device and delete resources created by the 
remainder of the procedures in the driver. 

A Queue I/O Procedure . This procedure must place the I/O requests on 
a queue of some sort, so that the device can process them when it 
becomes available. 

A Cancel I/O Procedure . This procedure must cancel a previously 
queued l/O request. 


In order for the I/O System to communicate with your device driver 
procedures, you must Include the addresses of these four procedures in 
the DUIBs which correspond to the units of the device. 

The next four sections describe the format of each of the I/O System 
calls to these four procedures. Your procedures must conform to these 
formats . 


I NITIALIZE I/O PROCEDURE 


The IRMX 86 I/O System calls the Initialize I/O procedure when an 
application task makes an RQ$A$PHYSICAL$ATTACH$DEVICE system call and no 
units of the device are currently attached. The iRMX 88 I/O System calls 
the Initialize I/O procedure when an application task attaches or creates 
a file on the device and no other files on the device are currently 
attached. In either case, the I/O System calls the Initialize I/O 
procedure before calling any other driver procedure. 
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The Initialize I/O procedure must perform any initial processing 
necessary for the device or the driver. If the device requires an 
interrupt task (or region or device data object, in the case of iRMX 86 
drivers), the Initialize I/O procedure should create it (them). 

The format of the call to the Initialize I/O procedure is as follows: 

CALL init$lo(duib$p, ddata$p, status$p); 

where: 


init$lo 


duib$p 


ddata$p 


status$p 


Name of the Initialize I/O procedure. You can use 
any name for this procedure as long as it does not 
conflict with other procedure names. You must, 
however, include its starting address in the DUIBs 
of all device-units that it services. 

POINTER to the DUIB of the device-unit for which 
the request is Intended. The lnlt$io procedure 
uses this DUIB to determine the characteristics of 
the unit. 

POINTER to a WORD in which the inlt$lo procedure 
can place the location of a data storage area, if 
the device driver needs such an area. If the 
device driver requires that a data area be 
associated with a device (to contain the head of 
the I/O queue, DUIB addresses, or status 
information), the init$io procedure should create 
this area and save its location via this pointer. 
If the driver does not need such a data area, the 
init$io procedure should return a zero via this 
pointer. 

POINTER to a WORD in which the lnlt$io procedure 
must place the status of the initialize operation. 
If the operation completes successfully, the 
lnit$io procedure must return the E$OK condition 
code. Otherwise it should return the appropriate 
exception code. If the init$lo procedure does not 
return the E$OK condition code, it must delete any 
resources that it has created and leave all data 
fields with exactly the same information that they 
contained prior to the call to inlt$io. 


FINISH I/O PROCEDURE 

The IRMX 86 I/O System calls the Finish I/O procedure after an 
application task makes an RQ$A$PHYSICAL$DETACH$DEVICE system call to 
detach the last unit of a device. The iRMX 88 I/O System calls the 
Finish I/O procedure when an application task detaches or deletes the 
last remaining file connection for the device. 
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The Finish I/O procedure performs any necessary final processing on the 
device* It must delete all resources created by other procedures in the 
device driver and must perform final processing on the device itself, if 
the device requires such processing* 

The format of the call to the Finish I/O procedure is as follows: 

CALL finish$lo(duib$p, ddata$t); 


where: 

f lnish$lo 


duib$p 


ddata$t 


Name of the Finish I/O procedure. You can specify 
any name for this procedure as long as it does not 
conflict with other procedure names. You must, 
however, include its starting address in the DUIBs 
of all device-units that it services. 

POINTER to the DUIB of a device-unit of the device 
being detached* The finish$io procedure needs this 
DUIB in order to determine the device on which to 
perform the final processing. 

WORD containing the location of the data storage 
area originally created by the init$io procedure. 
The finlsh$lo procedure must delete this resource 
and any others created by driver routines. 


QUEUE I/O PROCEDURE 


The I/O System calls the Queue I/O procedure to place an I/O request on a 
queue, so that it can be processed when the device is not busy. It is 
recommended that the Queue I/O procedure actually start the processing of 
the I/O request if the device is not busy* The format of the call to the 
Queue I/O procedure is as follows: 

CALL queue $io(lors$t, dulb$p, ddata$t); 


where: 

queue$lo 


lors$t 


Name of the Queue I/O procedure. You can use any 
name for this procedure as long as it does not 
conflict with other procedure names. You must, 
however. Include its starting address in the DUIBs 
of all device— units that it services. 

WORD containing the location of an lORS. This lORS 
describes the, request* When the request is 
processed, the driver (though not necessarily the 
queue$io procedure) must fill in the status fields 
and send the lORS to the response mailbox 
(exchange) indicated in the lORS. Chapter 2 
describes the format of the lORS* It lists the 
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information that the I/O System supplies when it 
passes the lORS to the queue$io procedure and 
indicates the fields of the lORS that the device 
driver must fill in. 

duib$p POINTER to the DUIB of the device-unit for which 

the request is intended. 

ddata$t WORD containing the location of the data storage 

area originally created by the init$io procedure. 
The queue$io procedure can place any necessary 
information in this area in order to update the 
request queue or status fields. 


CANCEL I/O PROCEDURE 


The I/O System can call the Cancel I/O procedure in order to cancel one 
or more previously queued I/O requests. The iRMX 88 I/O System does not 
call Cancel I/O, but in the iRMX 86 environment Cancel I/O is called 
under either of the following two conditions: 

• If the user makes an RQ$A$PHYSICAL$DETACH$DEVICE system call and 
specifies the hard detach option (refer to the iRMX 86 SYSTEM 
PROGRAMMER’S REFERENCE MANUAL for a description of this call). 
This system call forcibly detaches all objects associated with a 
device-unit . 

• If the job containing the task which made an I/O request is 
deleted. The I/O System calls the Cancel I/O procedure to remove 
any requests that tasks in the deleted job might have made. 

If the device cannot guarantee that a request will be finished within a 
fixed amount of time (such as waiting for input from a terminal 
keyboard), the Cancel I/O procedure must actually stop the device from 
processing the request. If the device guarantees that all requests 
finish in an acceptable amount of time, the Cancel I/O procedure does not 
have to stop the device Itself, but only removes requests from the queue. 

The format of the call to the Cancel I/O procedure is as follows: 

CALL cancel$io(cancel$id, duib$p, ddata$t); 


where: 

cancel$io 


cancel $id 


Name of the Cancel I/O procedure. You can use any 
name for this procedure as long as it doesn’t 
conflict with other procedure names. You must, 
however, include its starting address in the DUIBs 
of all device-units that it services. 

WORD containing the id value for the I/O requests 
that are are to be cancelled. Any pending requests 
with this value in the cancel$id field of their 
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IORS*s must be removed from the queue of requests 
by the Cancel I/O procedure. Moreover, the I/O 
System places a CLOSE request with the same 
cancel$id value in the queue. The CLOSE request 
must not be processed until all other requests with 
that cancel$id value have been returned to the I/O 
System. 

duib$p POINTER to the DUIB of the device-unit for which 

the request cancellation is intended. 

ddata$t WORD containing the location of the data storage 

area originally created by the init$io procedure. 
This area may contain the request queue. 


IMPLEMENTING A REQUEST QUEUE 


Making I/O requests via system calls and the actual processing of these 
requests by I/O devices are asynchronous activities. When a device is 
processing one request, many more can. be accumulating. Unless the device 
driver has a mechanism for placing I/O requests on a queue of some sort, 
these requests will become lost. The common and random access device 
drivers form this queue by creating a doubly linked list. The list is 
used by the QUEUE$IO and CANCEL$IO procedures, as well as by 
INTERRUPT$TASK. 

Using this mechanism of the doubly linked list, common and random access 
device drivers implement a FIFO queue for I/O requests. If you are 
writing a custom device driver, you might want to take advantage of the 
LINK$FOR and LINK$BACK fields that are provided in the lORS and implement 
a scheme similar to the following for queuing I/O requests. 

Each time a user makes an I/O request, the I/O System passes an lORS for 
this request to the device driver, in particular to the Queue I/O 
procedure of the device driver. The common and random access driver 
Queue I/O procedures make use of the LINK$FOR and LINK$BACK fields of the 
lORS to link this lORS together with lORSs for other requests that have 
not yet been processed. 

This queue is set up in the following manner. The device driver routine 
that is actually sending data to the controller accesses the first lORS 
on the queue. The LINK$FOR field in this lORS points to the next lORS on 
the queue. The LINK$FOR field in the second lORS points to the third 
lORS on the queue, and so forth until, in the last lORS on the queue, the 
LINK$FOR field points back to the first lORS on the queue. The LINK$BACK 
fields operate in the same manner. The LINK$BACK field of the last lORS 
on the queue points to the previous lORS. The LINK$BACK field of the 
second to last lORS points to the third to last lORS on the queue, and so 
forth, until, in the first lORS on the queue, the LINK$BACK field points 
back to the last lORS in the queue. A queue of this sort is illustrated 
in Figure 6-1. 
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Figure 6-1. Request Queue 


The device driver can add or remove requests from the queue by adjusting 
LINK$FOR and LINK$BACK pointers in the lORSs* 

To handle the dual problems of locating the queue and ascertaining 
whether the queue is empty, you can use a variable such as head$queue* 

If the queue is empty, head$queue contains the value 0. Otherwise, 
head$queue contains the address of the first lORS In the queue* 
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CHAPTER 7. BINDING A DEVICE DRIVER TO THE I/O SYSTEM 


You can write the modules for your device driver in either PL/M-86 or the 
MCS-86 Macro Assembly Language. However, you must adhere to the 
following guidelines: 

• If you use PL/M-86, you must define your routines as reentrant, 
public procedures, and compile them using the ROM and COMPACT 
controls. 

• If you use assembly language, your routines must follow the 
conditions and conventions used by the PL/M-86 COMPACT model of 
computation. In particular, your routines must function in the 
same manner as reentrant PL/M-86 procedures with the ROM and 
COMPACT controls set. The 8086/8087/8088 MACRO ASSEMBLER 
OPERATING INSTRUCTIONS FOR 8080/8085-BASED DEVELOPMENT SYSTEMS 
and the 8086/8087/8088 MACRO ASSEMBLER OPERATING INSTRUCTIONS FOR 
8086-BASED DEVELOPMENT SYSTEMS describe these conditions and 
conventions. 

If you are an iRMX 88 user, use the Interactive Configuration Utility to 
link your modules together and to the rest of the iRMX 88 executive. 

The remainder of this chapter applies only to iRMX 86 users. 

After you have created your device driver procedures and compiled or 
assembled them, you must link the object code to the I/O System. If you 
have written driver procedures for several types of devices, you might 
want to place all of these routines in a library and link this library to 
the I/O System. This allows you to maintain one file of driver routines 
and still link in only those routines that satisfy external references. 
The LIB86 command which allows you to create libraries of object modules 
is described in the 8086 FAMILY UTILITIES USER’S GUIDE FOR 
8080/8085-BASED DEVELOPMENT SYSTEMS and the lAPX 86 FAMILY UTILITIES 
USER’S GUIDE FOR 8086-BASED DEVELOPMENT SYSTEMS. 


The process of linking your driver procedures to the I/O System occurs at 
I/O System configuration time. The iRMX 86 CONFIGURATION GUIDE contains 
a description of this process. However, because the order in which you 
link the modules is Important and because you must modify the Submit file 
lOS.CSD, this chapter contains a brief description of the required LINK86 
command. 

The command used to link the I/O System is as follows: 


LINK86 

:fx: ITABLE.OBJ, 
;fx;IDEVCF.OBJ, 
:fx:drlver.obj, 
:fx:I00PTl.LIB, 
;fx;I0S.LIB, 
:fx:RPIFC.LIB 
TO :fx:los.lnk 


& 

& 

& 

& 

& 

& 

& 

(linker options) 
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where: 


fx The appropriate disk mnemonic. Indicating where the 

file resides* 

ITABLE.OBJ The assembled I/O System configuration flies. 
IDEVCF.OBJ 


driver. oh j The compiled or assembled code for your device 

drivers. This can be a library of procedures. 


lOOPTl.LIB I/O System options library. 

lOS.LIB I/O System library. 


RPIFC.LIB Interface library. 


Refer to the IRMX 86 CONFIGURATION GUIDE for a complete description of 
the I/O System configuration process. 
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This appendix describes, in general terms, the operations of the common 
device driver support routines. The routines described include; 

INIT$IO 

FINISH$IO 

QUEUE$IO 

CANCEL$IO 

INTERRUPT$TASK 

These routines are supplied with the I/O System and are the device driver 
routines actually called when an application task makes an I/O request of 
a common device. These routines ultimately call the user-written device 
initialize, device finish, device start, device stop, and device 
interrupt procedures. 

This appendix provides descriptions of these routines in order to show 
you the steps that an actual device driver follows. You can use this 
appendix to get a better understanding of the I/O System-supplied portion 
of a device driver in order to make writing the device-dependent portion 
easier (the random access driver support routines follow essentially the 
same pattern). Or you can use it as a guideline for writing custom 
device drivers. 


INIT$IO PROCEDURE 

The iRMX 86 I/O System calls INIT$IO when an application task makes an 
RQ$A$PHYSICAL$ATTACH$DEVICE system call and there are no units of the 
device currently attached. The IRMX 88 I/O System calls INIT$IO when an 
application task attaches or creates a file on the device and no other 
files on the device are attached. 

INIT$IO initializes objects used by the remainder of the driver routines, 
creates an Interrupt task, and calls a user-supplied procedure to 
initialize the device itself. 

When the I/O System calls INIT$IO, it passes the following parameters: 

• A pointer to the DUIB of the device-unit to Initialize 

• In the iRMX 86 environment, a pointer to the location where 
INIT$IO must return a token for a data segment (data storage 
area) that it creates 

• A pointer to the location where INIT$IO must return the 
condition code 
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The following paragraphs show the general steps that the INIT$IO 
procedure goes through In order to Initialize the device. Figure A-1 
Illustrates these steps. The numbers in the figure correspond to the 
step numbers In the text. 


INITSIO 








Figure A-1. Common Device Driver Initialize I/O Procedure 
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!• It creates a data storage area which will be used by all of the 
procedures In the device driver. The size of this area depends 
In part on the number of units In the device and any special 
space requirements of the device. INIT$IO then begins 
Initializing this area and eventually places the following 
Information there: 

• The value of the DS (data segment) register 

• A token (Identifier) for a region (exchange for mutual 

exclusion) 

• The address of the DUIB for this device-unit 

• A token (Identifier) for the Interrupt task 

• Other values Indicating that the queue Is empty and the 
segment Is not busy 

INIT$IO also reserves space In the data storage area for device 
data. 

2. It creates a region. The other procedures of the device driver 
gain access from this region whenever they place a request on the 
queue or remove a request from the queue. INIT$IO places a token 
for this region In the data object. 

3. It creates an Interrupt task. This Interrupt task handles the 
Interrupts generated by the device for which INIT$IO was called. 
INIT$IO places a token for this task In the data storage area. 

4. It calls a user-written device Initialization procedure that 
Initializes the device Itself. It gets the address of this 
procedure by examining the device Information table portion of 
the DUIB. Refer to Chapter 3 for Information on how to write 
this Initialization procedure. 

5. It returns control to the I/O System, passing a token for the 
data storage area and a condition code which Indicates the 
success of the Initialize operation. 


FINISH$IO PROCEDURE 

The IRMX 86 I/O System calls FINISH$IO when an application task makes an 
RQ$A$PHYSICAL$DETACH$DEVICE system call and there are no other units of 
the device currently attached. The IRMX 88 I/O System calls FINISH$IO 
when an application detaches or deletes a file and no other files on the 
device are attached. 

FINISH$IO deletes the objects used by the other device driver routines, 
deletes the Interrupt task, and calls a user-supplied procedure to 
perform final processing on the device Itself. 
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When the I/O System calls FINISH$IO, It passes the following parameters: 

• A pointer to the DUIB of the device-unit just detached 

• A pointer to the data storage area created by INIT$IO 

The following paragraphs show the general steps that the FINISH$IO 
procedure goes through in order to terminate processing for a device. 
Figure A-2 illustrates these steps. The numbers in the figure correspond 
to the step numbers in the text. 

1. It calls a user-written device finish procedure that performs any 
necessary final processing on the device itself. FINISH$IO gets 
the address of this procedure by examining the device information 
table portion of the DUIB. Refer to the Chapter 4 for 
information about device information tables. 


FINISH$IO 







Figure A-2. Common Device Driver Finish I/O Procedure 
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2. It deletes the interrupt task originally created for the device 
by the INIT$IO procedure and cancels the assignment of the 
interrupt handler to the specified interrupt level. 

3. It deletes the region and the data storage area originally 
created by the INIT$IO procedure, allowing the operating system 
to reallocate the memory used by these objects. 

4. It returns control to the I/O System. 


QUEUE $10 PROCEDURE 

The I/O System calls the QUEUE$I0 procedure in order to place an I/O 
request on a queue of requests. This queue has the structure of the 
doubly linked list shown in Figure 2-2. If the device itself is not 
busy, QUEUE$I0 also starts the request. 

When the I/O System calls QUEUE$I0, it passes the following parameters 

• A token (identifier) for the lORS | 

• A pointer to the DUIB 

• A token (identifier) for the data object originally created by I 

INIT$I0 ■ 

The following paragraphs show the general steps that the QUEUE$I0 
procedure goes through in order to place a request on the I/O queue. 

Figure A-3 illustrates these steps. The numbers in the figure correspond 
to the step numbers in the text. 

1. It sets the DONE field in the lORS to OH, indicating that the | 

request has not yet been completely processed. Other procedures 

that start the I/O transfers and handle interrupt processing also 
examine and set this field. 

2. It receives access to the queue from the region. This allows 
QUEUE$I0 to adjust the queue without concern that other tasks 
might also be doing this at the same time. 

3. It places the lORS on the queue. 

4. It calls an I/O System-supplied procedure in order to start the 
processing of the request. This results in a call to a 
user-written device start procedure which actually sends the data 
to the device itself. This start procedure is described in 
Chapter 5. If the device is already busy processing some other 
request, this step does not start the data transfer. 

5. It surrenders access to the queue, allowing other routines to 
insert or remove requests from the queue. 


A-5 



COMMON DRIVER SUPPORT ROUTINES 













COMMON DRIVER SUPPORT ROUTINES 


CANCEL$IO PROCEDURE 


The I/O System calls CANCEL$IO to remove one or more requests from the 
queue and possibly to stop the processing of a request, if it has already 
been started- The iRMX 86 I/O System calls this procedure in one of two 
instances: 

• If a user makes an RQ$A$PHYS1CAL$DETACH$DEV1CE system call and 
specifies the hard detach option (refer to the iRMX 86 SYSTEM 
PROGRAMMER’S REFEBIENCE MANUAL for information about this system 
call). The hard detach removes all requests from the queue. 

• If the job containing the task that makes an I/O request is 
deleted. In this case, the I/O System calls CANCEL$IO to remove 
all of that task’s requests from the queue. 

When the I/O System calls CANCEL$IO, it passes the following parameters: 

• An id value that identifies requests to be cancelled 

• A pointer to the DUIB 

• A token (identifier) for the device data storage area 

The following paragraphs show the general steps that the CANCEL$IO 
procedure goes through in order to cancel an I/O request. Figure A-4 
illustrates these steps. The numbers in the figure correspond to the 
step numbers in the text. 

1. It receives access to the queue from the region. This allows it 
to remove requests from the queue without concern that other 
tasks might also be processing the lORS at the same time. 

2. It locates a request that is to be cancelled by looking at the 
cancel$ld field of the queued lORSs, starting at the front of the 
queue. 

3. If the request that is to be cancelled is at the head of the 
queue, that is, the device is processing the request, CANCEL$IO 
calls a user-written device stop procedure that stops the device 
from further processing. Refer to the Chapter 5 for information 
on how to write this device stop procedure. 

4. If the request is finished, or if the lORS is not at the head of 
the queue, CANCEL$IO removes the lORS from the queue and sends it 
to the response mailbox (exchange) Indicated in the lORS. 

5. It surrenders access to the queue, allowing other procedures to 
Insert or remove requests from the queue. 

NOTE 

The additional CLOSE request supplied 
by the I/O System will not be processed 
until all other requests with the given 
cancel$id value have been dealt with. 
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INTERRUPT TASK (INTERRUPT$TASK) 

As a part of its processing, the INIT$IO procedure creates an interrupt 
task for the entire device. This Interrupt task responds to all 
Interrupts generated by the units of the device, processes those 
Interrupts, and starts the device working on the next I/O request on the 
queue. 

The following paragraphs show the general steps that the Interrupt task 
for the coiranon device driver goes through in order to process a device 
Interrupt. Figure A-5 illustrates these steps. The numbers in Figure 
A-5 correspond to the step numbers in the text. 

1. It uses the contents of the iAPX 86 DS register to obtain a token 
(identifier) for the device data storage area. This is possible 
because of the following two reasons: 

• When INIT$IO created the interrupt task, instead of 
specifying the correct contents of the DS register, it passed 
the address of the data object as the contents of the task*s 
DS register. 

• When the INIT$IO procedure created the data storage area, it 
included the correct contents of the DS register in one of 
the fields. 

When the interrupt task starts running, it saves the contents of 
the DS register (to use as the address of the data storage area) 
and sets the DS register to the value listed in the field of the 
data storage area. Thus the task has the correct value in its DS 
register and it has the address of the data storage area. This 
is the mechanism that is used to pass the address of the device's 
data storage area from the INIT$IO procedure to the interrupt 
task. 

2. It makes an RQ$SET$ INTERRUPT system call to Indicate that it is 
an interrupt task associated with the Interrupt handler supplied 
with the common device driver. It also indicates the interrupt 
level to which it will respond. 

3. It begins an Infinite loop by waiting for an interrupt of the 
specified level. 

4. Via a region, it gains access to the request queue. This allows 
it to examine the first entry in the request queue without 
concern that other tasks are modifying it at the same time. 

5. It calls a user-written device -interrupt procedure to process the 
actual interrupt. This can involve verifying that the interrupt 
was legitimate or any other operation that the device requires. 
This interrupt procedure is described further in Chapter 3. 
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Figure A-5. Connnon Device Driver Interrupt Task 
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If the request has been completely processed, (one request may 
require multiple reads or writes, for example), the interrupt 
task removes the lORS from the queue and sends it as a message to 
the response mailbox (exchange) indicated in the lORS. If the 
request is not completely processed, the interrupt task leaves 
the lORS at the head of the queue* 


If there are requests on the queue, the interrupt task initiates 
the processing of the next I/O request* 

In any case, the interrupt task then surrenders access to the 
queue, allowing other routines to modify the queue, and loops 
back to wait for another interrupt. 




APPENDIX B. EXAMPLES OF DEVICE DRIVERS 


This appendix contains three examples of device drivers. The first, a 
common driver, is a driver for a box with eight lights and eight 
switches. The second, also a common driver, drives a line printer. And 
the third, a random access driver, is a driver for the iSBC 206 disk 
controller. 

Note that the names of the procedures in the examples are not 
device$start , device$interrupt , etc., as in the text of this manual. 

This is because the actual names are placed, during configuration, in the 
appropriate DUIBs. 
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PL/M-86 COMPILER LIGHT 


SERIES-IIT PL/M-86 DEBUG X119 COMPILATION OF MODULE LIGHT 
OBJECT MODULE PLACED IN ;F5; LIGHT. OBJ 

COMPILER INVOKED BY; PLM86.86 : F5: LIGHT. P86 ROM COMPACT 


1 LIGHT; 

y****************A4r**'******A*****:k********A**************ik******4r4tlr* 

This driver is written to control a light/switch box 
attached to an iSBC508 I/O Expansion Board. The box consists of 
a series of 8 LED's (one for each bit) and 8 switches which 
allow a byte to be 'read* from the device. The box is attached 
to the board at port 0, and an interrupt level of the user's 
choosing (set at configuration time in the DUIB of the lOS) is 
triggered by a debouncing circuit attached to the appropriate 
Interrupt level on the Multibus. 

When the attachment is made to this device by a call to 
RQ$A$PHYSICAL$ATTACH$DEVICE, the box will light all LED's to 
indicate a successful attachment. When the device is detached, 
all LED's will be turned off. Anytime a read or write is done 
to or from the device, the interrupt must be manually triggered 
by the user to indicate that the device has successfully 
completed the transfer. 

In order to accomplish this, the device was treated as a 
coaimon device, thereby allowing the use of the default routines 
init$io, queue$io, finish$io, and cancelSio, In addition, the 
Intel supplied procedures default$stop and defaultSf inish were 
used, since no action was required of the device on any of 
these procedures. 

This device and driver combination are not Intended to be 
used in a practical application, but rather are meantto show 
the versatility and configurability of the device driver and to 
present a simple example of one. 


DO; 


2 

1 

DECLARE 

TRUE 

LITERALLY 

'0FFH' 


3 

1 

DECLARE 

FALSE 

LITERALLY 

' 0H ' 


4 

1 

DECLARE 

E$OK 

LITERALLY 

• 0H' 


5 

1 

DECLARE 

E$IDDR 

LITERALLY 

' 2AH' 


6 

1 

DECLARE 

E$IO 

LITERALLY 

' 2BH’ 


7 

1 

DECLARE 

F$READ 

LITERALLY 

' 0 • 


8 

1 

DECLARE 

F$WRITE 

LITERALLY 

• 1 • 


9 

1 

DECLARE 

F$SEEK 

LITERALLY 

• 2' 


10 

1 

DECLARE 

fSspecial 

LITERALLY 

' 3' 


11 

1 

DECLARE 

F$ATTACH$DEV 

LITERALLY 

' 4 ' 


12 

1 

DECLARE 

F$DETACH$DEV 

LITERALLY 

' 5' 


13 

1 

DECLARE 

F$OPEN 

LITERALLY 

* 6' 


14 

1 

DECLARE 

F$CLOSE 

LITERALLY 

• 7 • 


15 

1 

DECLARE 

ALL$LIGHTS$OFP 

LITERALLY 

'00000000B'; 
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PL/M 

16 

17 

18 

19 

20 
21 

22 


23 

24 

25 


86 COMPILER LIGHT 

1 DECLARE ALL$LIGHTS$ON LITERALLY 'llllllllB’; 

1 SET$LIGHTS; 

/* Routine to output the corresponding string to the light box */ 
PROCEDURE (PORT , NEW$VALUE ) REENTRANT ; 

2 DECLARE PORT WORD; 

2 DECLARE NEWSVALUE BYTE; 

2 OUTPUT (PORT) *NEW$VALUE; 

2 END SET$LIGHTS; 

1 READ$SWITCHES; 

/* Routine to read the switches on the front panel of the 
light box */ 

PROCEDURE (PORT) BYTE REENTRANT; 

2 DECLARE PORT WORD; 

2 RETURN ( INPUT (PORT) ); 

2 END READ$SWITCHES; 
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PL/M-86 compiler LIGHT 


$EJECT 

26 1 LIGHT$BOX$INIT$IO: 

PROCEDURE (D'JIB$PTR,DDATA$PTR,STATUS$PTR ) REENTRANT PUBLIC; 


This procedure will establish a connection to the lights by 
turning off all lights on all attached devices (as determined in 
the num$units in the common$device$ info block). 




27 

2 

DECLARE DUIB$PTR 

POINTER; 

28 

2 

DECLARE DUIB BASED 

DUIBSPTR STRUCTURE ( 



NAME (14 ) 

BYTE, 



FILE$DRIVERS 

WORD, 



FUNCTS 

BYTE, 



FLAGS 

BYTE, 



DEV$GRAN 

WORD, 



LOW$DEV$SIZE 

WORD, 



HIGH$DEV$SIZE 

WORD, 



DEVICE 

BYTE, 



UNIT 

BYTE, 



DEV$UNIT 

WORD, 



INIT$IO 

WORD, 



FINISH$IO 

WORD, 



QUEUE$IO 

WORD, 



CANCEL$IO 

WORD, 



DEVICE$INFO$PTR 

POINTER, 



UNIT$INFO$PTR 

POINTER, 



UPDATE$TIMEOUT 

WORD, 



NUM$BUFFERS 

WORD, 



PRIORITY 

BYTE) ; 

29 

2 

DECLARE STATUS$PTR 

POINTER; 

30 

2 

DECLARE DDATA$PTR 

POINTER; 

31 

2 

DECLARE COMMON$DEVIG 

E$INFO$PTR POINTER; 

32 

2 

DECLARE COMMON$DEVICE$INFO BASED 



COMMON$DEVICE$INFO$PTR STRUCTURE ( 



LEVEL 

WORD, 



PRIORITY 

BYTE, 



STACK $SIZE 

WORD, 



DATASSIZE 

WORD, 



NUM$UNITS 

WORD, 



DEVICE$INIT 

WORD, 



DEVICE$FINISH 

WORD, 



DEVICE$START 

WORD, 



DEVICE$STOP 

WORD, 



DEVICE$INTERRUPT 

WORD, 



BASE 

WORD) ; 

33 

2 

DECLARE INDEX 

WORD; 

34 

2 

COMMON$DEVICE$INFO$PTR»DUIB.DEVTCE$INFO$PTR; 

35 

2 

DO INDEX»0 TO (COMMON$DEVICE$INFO.NUM$UNITS-i: 

36 

3 

CALL SETSLIGHTS 

( (COMMON$OEVICE$INFO.BASE 


ALL$LIGHTS$OPF) ; 
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PL/M-86 COMPILER LIGHT 

37 3 END; 

38 2 END LIGHT$BOX$INIT$IO; 


39 1 LIGHT$BOX$START$IO: 

PROCEDURE (IORS$PTR,DUIB$PTR,DDATA$PTR) REENTRANT PUBLIC 


40 2 

41 2 


42 2 

43 2 

44 2 


45 2 

46 2 


DECLARE DUIB$PTR POINTER; 

DECLARE DUIB BASED DUIB$PTR STRUCTURE ( 
NAME(14) byte, 

FILE$DRIVERS WORD, 

functs byte, 

FLAGS BYTE, 

DEV$GRAN WORD, 

LOW$DEV$SIZE WORD, 

HIGH$DEV$SIZE WORD, 

DEVICE BYTE, 

UNIT BYTE, 

DEV$UNIT WORD, 

INIT$IO WORD, 

FINISHSIO WORD, 

QUEUE$IO WORD, 

CANCEL$IO WORD, 

DEVICE$INFO$PTR POINTER, 

UNIT$INFO$PTR POINTER, 

UPDATE$TIMEOUT WORD, 

NUM$BUFFERS WORD, 

PRIORITY BYTE); 

DECLARE DDATA$PTR POINTER; 

DECLARE COMMON$DEVICE$INFO$PTR POINTER; 

DECLARE COMMON$DEVICE$INFO BASED 

COMMON$DEVICE$INFO$PTR STRUCTURE ( 
LEVEL WORD, 

PRIORITY BYTE, 

STACKSSIZE WORD, 

DATA$SIZE WORD, 

NUMSUNITS WORD, 

DEVICE$INIT WORD, 

DEVICESFINISH WORD, 

DEVICE$START WORD, 

DEVICE$STOP WORD, 

DEVICE$INTERRUPT WORD, 

BASE WORD) ; 

DECLARE IORS$PTR POINTER; 

DECLARE lORS BASED IORS$PTR STRUCTURE ( 


STATUS 

UNIT$STATUS 

ACTUAL 

ACTUAL$FILL 

DEVICE 

UNIT 

FUNCT 

SUBFUNCT 

LOW$DEV$LOC 

HIGH$DEV$LOC 

BUFF$PTR 


WORD, 

WORD, 

WORD, 

WORD, 

WORD, 

BYTE, 

BYTE, 

WORD, 

WORD, 

WORD, 

POINTER, 
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47 2 

48 2 

49 2 

50 2 


51 2 


52 2 


53 3 

54 4 

55 4 

56 4 


57 3 

58 4 

59 4 

60 4 


61 3 

62 4 


63 3 

64 4 


65 3 

66 4 


COUNT 

WORD, 

COUNTSFILL 

WORD, 

AUXSPTR 

POINTER 

LINK$FOR 

POINTER 

LINK$BACK 

POINTER 

respSmbox 

WORD, 

DONE 

BYTE, 

FILL 

BYTE, 

CANCEL$ID 

WORD ); 


/* Initialize the I/O Structures */ 

COMMON$DEVICE$INFO$PTR=DUIB.DEVICE$INFO$PTR; 

IORS.STATUS=E$IDDR; 

IORS.ACTUAL=0; 

IORS.DONE=TRUE; 

/* Check for valid I/O functions */ 

IF (lORS.FUNCT <* F$CLOSE) THEN 
/* I/O function is valid, go ahead */ 

DO CASE (lORS.FUNCT); 

/* Read — Set done to false, since function will be finished 
by interrupt routine. Set status to E$OK, since 
function is valid. */ 

DO; 

IORS.DONE=FALSE; 

IORS.STATUS=E$OK; 

END; 

/* Write — Set done to false, since function will be finished 
by interrupt routine. Set status to E$OK, since 
function is valid. */ 

DO; 

IORS.DONE=FALSE; 

IORS.STATUS=E$OK; 

END; 

/* Seek — Function is invalid, return E$IDDR */ 

DO; 

END; 

/* Special — Function is invalid, return E$IDDR */ 

DO; 

END; 

/* Attach — Activate all lights, return E$OK */ 

DO; 

CALL SET$LIGHTS ( (COMMON$DEVICE$INFO. BASE + DUIB.UNIT), 
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67 4 

68 4 


69 3 

70 4 

71 4 

72 4 


73 3 

74 4 

75 4 


76 3 

77 4 

78 4 

79 3 

30 2 


ALL$LIGHTS$ON) ; 

IORS.STATUS=E$OK; 

END; 

/* Detach — Deactivate all lights, return E$OK. */ 

DO; 

CALL SET$LIGHTS ( (COMMON$DEVICE$INFO. BASE + DUIB.UNIT), 
ALL$LIGHTS$OFF) ; 

IORS.STATUS=E$OK; 

END; 

/* Open — Valid function, return E$OK */ 

DO; 

lORS . STATUS=E$OK; 

END; 

/* Close — Valid function, return E$OK */ 

DO; 

IORS.STATUS=E$OK; 

END; 

END; /* case */ 

END LIGHT$BOX$START$IO; 
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$EJECT 


81 1 


82 2 
83 2 


34 2 

85 2 

86 2 


87 2 

88 2 


LIGHT$BOX$INTERRUPT: 

PROCEDURE (IORS$PTR,DUIB$PTR,DDATA$PTR) REENTRANT PUBLIC 


DECLARE DUIB$PTR POINTER; 

DECLARE DUIB BASED DUIB$PTR STRUCTURE ( 

NAME (14) BYTE, 

FILE$DRIVERS WORD, 

FUNCTS BYTE, 

FLAGS BYTE, 

DEV$GRAN WORD, 

LOW$DEV$SIZE WORD, 

HIGH$DEV$SIZE WORD, 

DEVICE BYTE, 

UNIT BYTE, 

DEV$UNIT WORD, 

INIT$IO WORD, 

FINISH$IO WORD, 

QUEUE$IO WORD, 

CANCEL$IO WORD, 

DEVICE$INFO$PTR POINTER, 

UNIT$INFO$PTR POINTER, 

UPDATE$TIMEOUT WORD, 

NUM$BUFFERS WORD, 

PRIORITY BYTE); 

DECLARE DDATA$PTR POINTER; 

DECLARE COMMON$DEVICE$INFO$PTR POINTER; 

DECLARE COMMON$DEVICE$INFO BASED 

COMMON$DEVICE$INFO$PTR STRUCTURE ( 


LEVEL 

PRIORITY 

STACK$SIZE 

DATA$SIZE 

NUM$UNITS 

DEVICE$INIT 

DEVICESFINISH 

DEVICESSTART 

DEVICE$STOP 

DEVICESINTERRUPT 

BASE 

DECLARE IORS$PTR 

DECLARE lORS BASED 
STATUS 
UNIT$STATUS 
ACTUAL 
ACTUAL$FILL 
DEVICE 
UNIT 
FUNCT 
SUBFUNCT 
LOW$DEV$LOC 
HIGH$DEV$LOC 
BUFF$PTR 
COUNT 

COUNT$FILL 


WORD, 

BYTE, 

WORD, 

WORD, 

WORD, 

WORD, 

WORD, 

WORD, 

WORD, 

WORD, 

WORD) ; 
POINTER; 

IORS$PTR STRUCTURE 
WORD, 

WORD, 

WORD, 

WORD, 

WORD, 

BYTE, 

BYTE, 

WORD, 

WORD, 

WORD, 

POINTER, 

WORD, 

WORD, 


( 
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PL/M-86 COMPILER LIGHT 


89 2 

90 2 


91 2 

*92 2 

93 3 

94 3 

95 3 


96 4 


97 4 


98 4 

99 3 

100 3 

101 3 

102 4 

103 4 

104 4 

105 3 

106 2 

107 1 


AUX$PTR 

LINK$FOR 

LINK$BACK 

RESP$MBOX 

DONE 

FILL 

CANCELSID 

DECLARE BUFFER$PTR 


POINTER, 

POINTER, 

WORD, 

BYTE, 

BYTE, 

WORD ); 

POINTER; 


DECLARE BUFFER BASED BUFFER$PTR (1) BYTE; 


/* Check for a valid interrupt */ 

IF (IORS$PTR<>0) THEN 
DO; 

COMMON$DEVICE$INFO$PTR=DUIB.DEVICE$INFO$PTR; 

BUFFER$PTR=IORS.BUFF$PTR; 


DO CASE (lORS.FUNCT) ; 

/* Read — Bring in switch reading */ 


BUFFER (IORS.ACTUAL)=READ$SWITCHES ( 

COMMON$DEVICE$INFO.BASE + DUIB.UNIT); 

/* Write — Output light pattern */ 

CALL SET$LIGHTS ( (COMMON$DEVICE$ I N FO . BASE + DUIB.UNIT), 

BUFFER (lORS. ACTUAL)); 


END; 

IORS.ACTUAL*IORS.ACTUAL+l; 

IF (IORS.ACTUAL=IORS. COUNT) THEN 
DO; 

IORS.STATUS=E$OK; 

IORS.DONE=TRUE; 

END; 

END; 

END LIGHT$BOX$INTERRUPT; 

END LIGHT; 


MODULE INFORMATION: 


CODE AREA SIZE 

* 

021BH 

539D 

CONSTANT 

AREA 

SIZE = 

0000H 

0D 

VARIABLE 

AREA 

SIZE » 

0000H 

0D 

MAXIMUM 

STACK 

SIZE » 

001EH 

30D 


377 LINES READ 
0 PROGRAM WARNINGS 
0 PROGRAM ERRORS 

END OF PL/M-86 COMPILATION 
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PL/M-86 COMPILER iprntr.p86 

printers Starts interrupt 

SERIES-III PL/M-86 DEBUG X119 COMPILATION OF MODULE IPRNTR 
OBJECT MODULE PLACED IN ; FI : IPRNTR. OBJ 

COMPILER INVOKED BY; PLM86.86 ; FI ; IPRNTR . P86 COMPACT ROM NOTYPE OPTIMIZE(3) 



Stitle ( ' iprnt r . p86 ' ) 

/* 

* iprntr.p86 

* 

* This module implements Centronix- type interface line printer 

* driver. It Is written as a 'common* device driver. It is 

* assumed that the reader is familiar with the 8255 chip. 

* 

* LANGUAGE DEPENDENCIES; 

* COMPACT ROM OPTIMIZE (3) 

*/ 

$ include( ; f 1; icpyrt.not) 

= /* 

= * INTEL CORPORATION PROPRIETARY INFORMATION. THIS LISTING IS 

= * SUPPLIED UNDER THE TERMS OF A LICENSE AGREEMENT WITH INTEL 

= * CORPORATION AND MAY NOT BE COPIED NOR DISCLOSED EXCEPT IN 

= * ACCORDANCE WITH THE TERMS OF THAT AGREEMENT. 

= */ 

1 iprntr; DO; 

$include(;fl; icomon.lit) 

= Ssave nolist 

$ include (; fl ; iparam. 1 i t) 

= Ssave nolist 

$ include( ; f 1; inutyp.l it) 

= Ssave nolist 

Sinclude(;fl; iiors.lit) 

= Ssave nolist 

$include(;fl; iduib.lit) 

= Ssave nolist 

Sinclude(;fl; iprntr. lit) 

= /* 

= * Common device driver information 

s * 

=» * level; 

= * priority; 

= * stackSsize; 

= * dataSsize; 

= * numSunits; 

=* * deviceSinit; 

= * deviceSf inish; 

= * deviceSstart ; 

= * deviceSstop; 

= * devices interrupt: 

=* */ 

13 1 = DECLARE COMMONSDEVSINFO LITERALLY ' 


level WORD, 
priority BYTE, 
stackSsize WORD, 
dataSsize WORD, 


Interrupt level 
Priority of interrupt task 
Stack size for interrupt task 
Device local data size 
Number of units on device 
Tnit device procedure 
Finished with device procedure 
Start device procedure 
Stop device procedure 
Device Interrupt procedure 
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COMPILER 

iprntr .p86 
pr lnter$start$ 

interrupt 

_ 

numS units 

WORD, 

= 

devices ini t 

WORD, 


deviceSf inish 

WORD, 

= 

deviceSstart 

WORD, 

= 

deviceSstop 

WORD, 

=S 

devices interrupt 

WORD' 


14 1 


DECLARE 18255$INFO LITERALLY ' 


A$port WORD, 

B$port WORD, 

C$port WORD, 

ControlSport WORD'; 


15 


1 = 


DECLARE 

PRINTER$DEVICE$INFO LITERALLY ' STRUCTURE ( 
COMMON$DEV$INFO, 
i8255$INFO, 
tabScontrol WORD)'; 

$include(; fl: 18255. lit) 

/* 

8255 is programmed as follows: 


Group A: 
Group B: 


Mode 

Mode 


= 

* 

Port A and 

Upper Port 

C: 

OUTPUT 

= 

* 

4r 

Port B and 

Lower Port 

C; 

INPUT 

= 

* 

Port C defini 

tion (bit 0 

is 

LSB; 


bit 7 is MSB) 


Bit 


15 


18 


*/ 

DECLARE 


0 
1 
2 

3 

4 

5,6,7 


Interrupt to CPU (not used by the driver) 
Character acknowledge from the printer 
Printer interrupt enable 


Paper error status (not 
Character strobe to the 
not used 


used by the driver) 
printer 


= 

MODESWORD 

LITERALLY 

'87H 


charSack 

LITERALLY 

'02H 

= 

INTSENABLE 

LITERALLY 

'0 5H 

= 

INTSDISABLE 

LITERALLY 

'0 4H 

= 

strobeson 

LITERALLY 

'09H 


STROBESOFF 

LITERALLY 

'08H 


$include(:fl:iprerr.lit) 
$save nolist 

/* 

* literal declaration 

*/ 

DECLARE 

TAB$CHAR LITERALLY '09H 
SPACE LITERALLY '20H 
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19 

20 
21 

22 

23 


24 


25 

26 


27 

28 

29 

30 


31 

32 

33 

34 


35 


EXAMPLES OF DEVICE DRIVERS 


-86 COMPILER iprntr.p36 

printers Starts interrupt 


Se j ect 

Ssubtitle( ’printers Starts interrupt' ) 

/* 

* pr inters star t/pr inters interrupt 

start/interrupt procedure for the line printer 


CALLING SEQUENCE: 

CALL printerSstartS interrupt (iorsSp, duibSp, ddataSp) ; 
INTERFACE VARIABLES: 


* 

iorsSp 

I/O reques 

t/resul t 

* 

duibSp 

pointer 

to 

the dev 

* 

ddataSp 

pointer 

to 

the dev 


CALLS: None 


* 

*/ 


printerSstartS interrupt: PROCEDURE (iorsSp, duibSp, ddataSp) 

PUBLIC REENTRANT; 

DECLARE 

(iorsSp, duibSp, ddataSp) 

DECLARE 
iors 
duib 
DECLARE 

dinfoSp POINTER, 
d inf o 
DECLARE 

bufferSp POINTER, 

(char BASED bufferSp) (1) BYTE; 


POINTER; 


BASED iorsSp IOSREQSRESSSEG, 

BASED duibSp DEVSUNITSINFOSBLOCK; 


BASED dinfoSp PRINTERSDEVICESINFO; 


dinfoSp » duib. devices infoSp; 




V 


test for spurious interrupts 


IF iorsSp = 0 THEN 
DO; 

/* 

* turn off the interrupt and return 

*/ 

OUTPUT (dinfo.ControlSport) = INTSDISABLE; 
RETURN; 

END; 


DO CASE ( iors. f unct) ; 


3 

4 
4 
4 


3 


/* read */ 

DO; 

iors. status » ESiDDR; 
iors. done » TRUE; 

END; 

/* write */ 

DO; 
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36 

37 

38 


39 


41 


42 

43 


44 


45 

46 


47 

48 

49 

50 


51 

52 

53 


-86 COMPILER 


iprntr . p36 

printer$start$ interrupt 


/* get the buffer pointer */ 
buffer$p = iors.buffSp; 

/* disable printer interrupt */ 

OUTPUT (dinfo.Control$port) = INT$DTSABLE; 

DO WHILE (iors. actual < iors. count); 


/* 

* 


convert TAB character to a SPACE character if the 
printer does not handle them 


IF 

{ (char ( iors. actua 

1^ = TAB$CHAR) AND 




( (d 

info 

. tabScontrol) 

=* FALSE 


THEN char(iors.a 

ctual) = 

SPACE; 


/* 






* 

I's complement the charac 

ter 

and send it to the 

* 

printer. Port-A 

is the d 

ata 

port 


* 

/ 




OUTPUT (dinfo. A$port) 

II 

o 

-3 

O 

har ( 

iors. actual) ) 

0 

/* 






* 

strobe the line p 

r inter 




* 

this is a way of 

tell ing 

the 

printer that 

there is 

* 

valid data on the 

bus 





*/ 

OUTPUT (dinfo.ControlSport) = STR08E$0M; 

OUTPUT (dinfo.ControlSport) = STR03E$0FF; 

/* 

* increment the count of chars printed 

*/ 

iors. actual = iors. actual + 1; 

/* 

* test whether printer acknowledgement bit is set 

*/ 

IF (INPUT (dinfo.CSport) AND CHARSACK) = 0 THEN 
DO; 



/* 




* 

printer 

didn' 


* 

started 

print 


* 

and retu 

rn(pr 


*/ 



6 

OUTPUT (dinfo 

. Cont 


RETURN; 

END; 

ELSE 

DO; 

/* 

* printer copied the character into its buffer 

* clear printer acknowledge bit by reading port B. 

* actual$fill field in the iors is used as a tempo- 

* rary variable. Char read is ignored. 

*/ 

iors. actual$f ill =* INPUT (d inf o. B$port) ; 

END; 

END; /* end of DO WHILE statement */ 
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iprntr .p86 

pr in ter$ Starts interrupt 



/* 



* set iors.done to TRUE 

* set iors. status to OK 

*/ 

54 

4 

iors. status = E$OK; 

55 

4 

iors.done * TRUE; 

56 

4 

END; 



/* seek */ 

57 

3 

DO; 

58 

4 

iors. status = ESIDDR; 

59 

4 

iors.done - TRUE; 

60 

4 

END; 



/* special */ 

61 

3 

DO; 

62 

4 

iors. status = ESIDDR; 

63 

4 

iors.done = TRUE; 

64 

4 

END; 



/* attach device */ 

55 

3 

DO; 



/* initialize the 8255 */ 

66 

4 

OUTPUT (dinfo.ControlSport) = MODESWORD 

67 

4 

iors. status = E$OK; 

68 

4 

iors.done = TRUE; 

59 

4 

END; 



/* detach device */ 

70 

3 

DO; 

71 

4 

iors. status = E$OK; 

72 

4 

iors.done * TRUE; 

73 

4 

END; 



/* open */ 

74 

3 

DO; 

75 

4 

iors. status = E$OK; 

76 

4 

iors.done = TRUE; 

77 

4 

END; 



/* close */ 

78 

3 

DO; 

79 

4 

iors. status “ E$OK; 

80 

4 

iors.done =* TRUE; 

81 

4 

END; 

82 

3 

END; /* end of DO CASE statement */ 

83 

2 END 

printers Starts interrupt; 
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printerSstop 


$subtitle( ' pr inter$3top* ) 

/* 

* nr t n^^»r6 «»-rkn 


* 

pr inter$stop 



* 

* 

stop procedure for the line printer 


* 

CALLING SEQUENCE: 



* 

* 

CALL printerSstop (iorsSp, duibSp, ddataSp); 

* 

INTERFACE VARIABLES: 


* 

iorsSp - 

I/O request/result segment 

pointer 


duibSp 

pointer to the device-unit 

info, block 

* 

* 

ddataSp - 

pointer to the device (printer) data segment 

* 

It 

CALLS; None 



*/ 





84 1 

35 2 

86 2 
87 2 


printerSstop; PROCEDURE (iors$p, duib$p, ddata$p) PUBLIC REENTRANT 
DECLARE 

(iors$p, duibSp, ddataSp) POINTER; 

DECLARE 

iors BASED iors$p IO$REQ$RES$SEG , 

duib BASED duibSp DEV$UNIT$INFO$BLOCK; 

DECLARE 

dinfoSp POINTER, 

dinfo ‘ BASED dinfoSp PRINTER$DEVICE$INFO; 


/* 

* 

turn 

off the printer interrupt 

* 

set 

iors. done to TRUE 

* 

set 

iors. status to E$OK 

*/ 




88 

2 


dinfoSp = duib. devices inf oSp; 

89 

2 


OUTPUT (dinfo. ControlSport) =» INTSDISABLE; 

90 

2 


iors. status » ESoK; 

91 

2 


iors. done » TRUE; 

92 

2 

END 

printerSstop; 

93 

1 

END 

iprntr; 


MODULE INFORMATION: 


CODE AREA SIZE 

S 

0140H 

320D 

CONSTANT 

AREA 

SIZE =* 

0000H 

0D 

VARIABLE 

AREA 

SIZE » 

0000H 

0D 

MAXIMUM 

STACK 

SIZE = 

0016H 

22D 


500 LINES READ 
0 PROGRAM WARNINGS 
0 PROGRAM ERRORS 


END OF PL/M-86 COMPILATION 


EXAMPLES OF DEVICE DRIVERS 


PL/M-86 COMPILER i206ds.p86 

Module Header 


SERIES-III PL/M-86 DEBUG X119 COMPILATION OF MODULE I206DS 
OBJECT MODULE PLACED IN ; F5 ; I 206DS . OBJ 

COMPILER INVOKED BY; PLM86.86 ; F5 ; 1 206DS .P86 COMPACT NOTYPE OPTIMIZE (3) ROM 


1 


$title('i206ds.p86') 
Ssubtitle ( 'Module Header') 

/* 


* 

A 

i206ds.p86 




* 

CONTAINS; 




* 

i206$start 

maps 

to 

device$ ini t . 

* 

i206$ interrupt 

maps 

to 

device$ interrupt 

* 

i206$init 

maps 

to 

device$start. 


* 


* This module contains the procedures that are referenced 

* in the device information tables. 

* 

* LANGUAGE DEPENDENCIES; COMPACT ROM OPTIMIZE (3) 

*/ 

i206ds; DO; 


$ include (; fl : 
$save nolist 
$include( ; f 1; 
$save nolist 
$ include( ; f 1; 
$save nolist 
$ include {; fl ; 
$save nolist 
$ include( ; f 1; 
$save nolist 
$ include ( ; f 1 ; 
$save nolist 
$ include( ; f 1; 
$save nolist 
$ include( ; f 1 ; 
$save nolist 
$ include ( ; f 1 : 
$save nolist 
$ include (; fl : 
$save nolist 
$ include( ; f 1; 
$save nolist 
$ include ( : f 1 ; 
$save nolist 


icomon. lit) 
inutyp.lit) 
iparam.lit) 
i iotyp.l it) 
i iors.l it) 
iduib. 1 i t) 
idrinf .1 it) 
i 206 in. 1 it) 
i206dv. 1 it) 
iexcep.l it) 
i ioexc .lit) 
i radsf . 1 i t) 


$ include( ; f 1; i 20 6 dp. ext) 
$save nolist 
$include(:fl; i206dc.ext) 
$save nolist 
$ include( : f 1: i206fm.ext) 
$save nolist 


PL/M-86 COMPILER i206ds.p86 

Module Header 


$ include (; fl ; iasmut.ext) 
$save nolist 

$include(;fl; inotif.ext)' 
$save nolist 
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Local Data 

$subtitle( 'Local Data') 

/* 

* The need$reset array is used to determine if device needs to be 

* reset after an error. Indexed by status. 

* 

* TRUE * 0FFH 

* FALSE = 000H 

*/ 

49 1 DECLARE 


need$ reset (24 ) 

BYTE DATA( 

FALSE, 

/* 

Successful completion */ 

TRUE, 

/* 

ID field miscompare */ 

FALSE , 

/* 

Data field CRC error */ 

FALSE, 

/* 

special for incorrect result$type */ 

TRUE , 

/* 

Seek error */ 

FALSE, 



FALSE, 



FALSE, 



FALSE, 

/* 

Illegal Record Address */ 

FALSE, 



FALSE, 

/* 

ID Field CRC error */ 

TRUE, 

/* 

Protocol error */ 

TRUE, 

/* 

Illegal Cylinder Address */ 

FALSE, 



FALSE, 

/* 

Record not found */ 

FALSE, 

/* 

Data Mark Missing */ 

FALSE, 

/* 

Format Error */ 

FALSE, 

/* 

Write Protected */ 

FALSE, 



TRUE, 

/* 

Write Error */ 

FALSE, 



FALSE , 



FALSE, 



FALSE) ; 

/* 

Drive Not Ready */ 
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Unit Status Array 

$subtitle ( 'Unit Status Array') 


/* 




* 

unitSstatus is used 

to 

set the unit status field in iors. 

* 

It 

Indexed by status. 



* 

lOSUNCLASS =* 



* 

lOSSOFT = 



* 

IOSHARD = 



* 

lOSOPRINT = 



* 

lOSWRPROT = 



*/ 




DECLARE 




unitSstatus (24 ) 

BYTE DATA{ 


IOr$UNCLASS , 

/* 

Successful completion */ 


lOSSOFT, 

/* 

ID field miscompare */ 


TOSSOFT, 

/* 

Data field CRC error */ 


IOSHARD, 

/* 

special for incorrect resultStype */ 


lOSSOFT, 

lOSUNCLASS, 

lOSUNCLASS, 

lOSUNCLASS, 

/* 

Seek error */ 


ioShard, 

lOSUNCLASS, 

/* 

Illegal Record Address */ 


lOSSOFT, 

/* 

ID Field CRC error */ 


lOSSOFT, 

/* 

Protocol error */ 


ioShard, 

lOSUNCLASS, 

/* 

Illegal Cylinder Address */ 


lOSSOFT, 

/* 

Record not found */ 


lOSSOFT, 

/* 

Data Mark Missing */ 


lOSSOFT, 

/* 

Format Error */ 


lOSWRPROT, 

lOSUNCLASS, 

/* 

Write Protected */ 


lOSSOFT, 

lOSUNCLASS, 

lOSUNCLASS, 

lOSUNCLASS, 

/* 

Write Error */ 


lOSOPRINT) ; 

/* 

Drive Not Ready */ 

/* 




* 

drives ready is used 

to 

find t^e drive ready bit 

* 

in the drive status 

• 


*/ 

51 1 DECLARE 

drives ready (4) BYTE DATA(020H,040H,010H,020H) ; 
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i206$start 


52 1 

53 2 


54 2 


$subtitle( ' i206$start* ) 


/* 

* i206$start 

* start procedure for the iSBC 206 controller. 

* 

* CALLING SEQUENCE: 

* CALL 1 206$start ( iors$p, duib$p, ddata$p) ; 

* 

* INTERFACE VARIABLES: 

* iors$p - I/O Request/Result segment pointer 

* duib$p - pointer to Device-Unit Information Block 

* ddatalp - device data segment pointer. 

* 

* CALLS: 

* io$206 

* format$206 

* send$206$ iopb 

* 

* CALLED FROM: 

* radev via a reference in the device info table. 


* ABSTRACT: 


* 

*/ 


This is the device start procedure called by Random 
Access Interface (radev). The device is assumed to 
have been initialized, any necessary resources 
allocated and the interrupt task has already been 
created. All requests to any number of 
iSBC 206 controller board's are funneled through this 
procedure. The reentrant nature of the procedure will 
allow multiple invocations with only one copy of the 
code. The nature of the request is passed in as the 
function code and sub-function fields of the lORS. 

The function provides a simple method to DO CASE into 
the required procedures. 


i206$start: PROCEDURE (iors$p, duib$p, ddata$p) PUBLIC REENTRANT 
DECLARE 


iors$p 
duib$p 
ddata$p 
DECLARE 
iors 
duib 
d info$p 
d info 
uinfoSp 
uinfo 
ddata 
base 
dummy 


POINTER, 

POINTER, 

POINTER; 

BASED iorsSp IO$REQ$RES$SEG, 

BASED duib$p DEV$UNIT$INFO$BLOCK, 
POINTER, 

BASED dinfo$p I206$DEVICE$INFO, 
POINTER, 

BASED uinfo$p I206$UNIT$INFO, 
BASED ddata$p IO$PARM$BLOCK$206 , 
WORD, 

BYTE; 


/* 

* Initialize the local variables. 
*/ 
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i206$start 


55 2 

56 2 

57 2 


dinfo$p = duib. devices info$p; 

base = dinfo.base; 

uinfoSp = duib. units inf oSp; 


62 4 

53 4 


55 4 

56 4 


63 4 

69 4 


82 4 


* If we got called because of a restore operation 

* then just return, 

*/ 

IF (ddata. restore) THEN 
RETURN; 

doScaseS f unct ; 

DO CASE iors.funct; 

/* 

* in the following calls the @ddata is literally 

* iopbSp (i.e., the pointer to the iopb) . 

*/ 

caseS read : 

DO; 

CALL ioS206 (base, iorsSpr duibSp, Qddata) ; 

END caseSread; 

caseSwr ite; 

DO; 

CALL ioS206(base, iorsSp, duibSp, @ddata); 

END caseSwrite; 

caseSseek; 

DO; 

CALL ioS206 (base, iorsSp, duibSp, @ddata) ; 

END caseSseek; 

caseS specS f unct : 

DO; 

IF iors.subSfunct = FSSFORMATSTRACK THEN 

CALL f ormatS206 (base, iorsSp, duibSp, §ddata) ; 

ELSE 

DO; 

/* 

* Notifiy caller that this is an 

* Illegal Device Driver Request. 

*/ 

iors. status = ESiDDR; 
iors. actual » 0; 
iors. done = TRUE; 

END; 

END caseSspecSfunct; 

caseS at tachSdevlce: 

DO; 

dummy = (duib.devSgran = 512); 

IF (( input (subSsystemSport) OR 073H) <> 0PBH) OR 
((( input (diskSconfigSport) AND 

SHL(010H,SHR(duib.unit,2) ) ) <> 0) <> dummy) THEN 

DO: 


B-20 


EXAMPLES OF DEVICE DRIVERS 


PL/M-86 compiler i206ds.p86 

i206$start 


83 5 

84 5 

85 5 

86 5 

87 5 

88 5 

89 4 

90 4 

91 4 


92 4 

93 5 


94 5 

95 5 

96 5 

97 5 

98 4 


lors. status = E$IO; 
lots. unit$status = IO$OPRINT; 
iors. actual = 0; 
iors.done = TRUE; 

RETURN; 

END; 

ddata. inter = inter$on$mask; 
ddata.instr = restore$op; 

IF NOT send$206$ iopb(base, ?ddata) THEN 

/* 

* the board would not accept the iopb 

* so. . . 

*/ 

DO; 

iors. status = E$TO; 

/* 

* insert the result code into unit status 

* so the user has access to the code. 

* This will assist in debugging. 

*/ 

iors.unit$status = TO$SOPT OR 

SHL ( input ( result$byte$ port) , 8); 
iors. actual = 0; 
iors.done = TRUE; 

END; 

END case$attach$device; 


99 3 

100 4 

101 4 

102 4 


case$detach$device; 

DO; 

iors. status = E$OK; 
iors.done = TRUE; 
END case$detach$device; 


103 3 


104 4 

105 4 

106 4 


case$open: 

DO; 

iors. status = E$OK; 
iors.done = TRUE; 
END case$open; 


107 3 


108 4 

109 4 

110 4 


case$close: 

DO; 

iors. status = E$OK; 
iors.done = TRUE; 
END case$close; 


111 3 


END do$case$ funct; 


112 2 END i206$start; 
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i206ds.p86 
i206$ interrupt 


$ subtitle ( ' i206$ interrupt’ ) 




i 206$ interrupt 

interrupt procedure for the ISBC 206 controller. 
CALLING SEQUENCE: 

CALL i206$interrupt(iors$p, duib$p, ddata$p); 

INTERFACE VARIABLES: 

iors$p - I/O Request/Result segment pointer 

duib$p - pointer to Device-Unit Information Block 

ddata$p - device data segment pointer. 

CALLS: 

i206$start 
send$206$ iopb 
rq$send$ message 

CALLED FROM: 

radev via a reference in the device info table. 


ABSTRACT: 

This procedure will handle the interrupts from the 
iSBC 206 controller and will initiate any actions 
necessary to recover from an error condition 
(there are some conditions that are not recoverable) . 


/ 


113 

1 

1206$ interrupt: 

PROCEDURE (iors$p, duib$p, ddata$p) 




PUBLIC REENTRANT 

114 

2 

DECLARE 




iors$p 

POINTER, 



duib$p 

POINTER, 



ddata$p 

POINTER; 

115 

2 

DECLARE 




iors 

BASED iors$p IO$REQ$RES$SEG, 



duib 

BASED duib$p DEV$UNIT$INFO$BLOCK , 



d info$p 

POINTER, 



d info 

BASED dinfo$p I206$DEVICE$INFO, 



ddata 

BASED ddata$p IO$PARM$BLOCK$206 , 



temp 

BYTE, 



base 

WORD, 



spindle 

WORD, 



status 

WORD; 



/* 




* Initialize the local variables. 



*/ 


116 

2 

dinfo$p = duib.device$ info$p; 

117 

2 

base = dlnfo 

.base; 

118 

2 

spindle = shr (duib. uni t , 2); /* 4 units/spindle *> 



/* 




* input from the result type port and 



* mask out 

all the unused bits. 
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*/ 

119 2 IF ( input ( result$type$port) AND 3) = 0 THEN 

120 2 done$int: 

DO; 

121 3 status = input ( result$byte$ port) ; 


122 3 

123 3 

124 4 

125 4 

126 4 


127 4 

128 5 


129 5 


130 4 

131 4 


IF ddata . restore THEN 
did$ restore: 

DO; 

ddata, restore = FALSE; 

ddata .status (spindle) = status; 

IF iors$p <> 0 THEN 
/* 

* There is a valid iors and we have 

* just returned from a restore operation 

* so, reinitiate the request. 

*/ 

restart: 

DO; 

CALL i 206$start ( iors$p, 
ddata$p, 
duib$p) ; 

END restart; 

/* 

* That is all we can do so ... 

*/ 

RETURN; 

END did$restore; 


132 3 


ddata. status (spindle) = status; 


133 3 

134 3 

135 4 

136 4 

137 5 

138 5 

139 5 

140 5 

141 5 


142 5 

143 5 


144 5 

145 5 


IF iors$p <> 0 THEN 
val id$ iors: 

DO; 

IF status <> 0 THEN 
bad$status: 

DO; 

iors. status * E$IO; 

IF (status <= 010H) THEN 
temp = status; 

ELSE 

temp = shr(status, 4) + 00FH; 
iors.unit$status = unit$status(temp) 

OR SHL (status, 8); 

iors. actual = 0; 
iors. done * TRUE; 

/* 

* Index into the need$ reset array 

* to determine the next course of 

* action. 

*/ 

IF need$ reset (ddata. status 

(iors. unit / 4)) THEN 

recal ibrate: 

DO; 

/* 
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146 

147 

148 


149 

150 

151 


152 

153 

154 

155 

156 

157 


158 

159 

160 
161 
162 

163 

164 

165 


166 

167 

168 

169 
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i 206ds . p86 
1206$ interrupt 


* No 

te; must 

index drive 

* se 

lect bits 

from iors. unit. 

*/ 



ddata 

. inter = 

inter$on$mask; 

ddata 

.instr = 

restore$op; 

ddata 

. restore 

= send$206$ iopb ( 



dinfo.base 



Qddata) ; 

recal 

ibrate; 



END bad$status; 
ELSE ok$status; 

DO; 

/* 

* 

* 

* 


set actual = count as the status 
indicated that the transfer worked. 
This is done regardless of the 
operation preformed. 


*/ 

iors. actual = iors. count; 
iors.done = TRUE; 


END ok$status; 
END valid$iors; 

END done$int; 

ELSE status$int: 

DO; 


/* 

4r 

* 

■k 

* 


Have arrived here because of an interrupt 
initiated by the drive itself. 

Could have been a drive ready or not ready 
signal. 


*/ 

temp = input ( inter$stat$port) ; 

DO spindle*0 TO 3; 

IF (temp AND SHL(1, spindle)) <> 0 THEN 
GOTO found$ spindle; 

END; 

found$spindle: 

spindle =* SHL (spindle, 2) ; 

DO temp=spindle TO spJ.ndle+3; 

IF (( input ( result$byte$port) AND 

drive$ready (spindle) ) = 0) THEN 
/* 

* let the user know the status 

* of the drive. 

*/ 

CALL notify(temp, 0ddata) ; 

END; 

END status$lnt; 


END 1206$ interrupt; 
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$subtitle( ' i206$init' ) 


/* 

* i206$init 

* init procedure for the iSBC 206 controller. 

* 

* CALLING SEQUENCE: 

* CALL i 206$ ini t (duib$ p, ddata$p, status$p) ; 

* 

* INTERFACE VARIABLES: 

* duib$p - pointer to Device-Unit Information Block 

* ddata$p - device data segment pointer. 

* status$p - pointer to WORD indicating status of 

* the operation. 

* 

* CALLS; 

* <none> 

* 

* CALLED FROM; 

* radev via a reference in the device info table. 

* 

* ABSTRACT; 

* initialize the hardware when called. 

* There is not much to do. 

*/ 


170 1 

171 2 


172 2 


173 2 

174 2 

175 2 

176 2 

177 2 

178 2 


i206$init: PROCEDURE (duib$p, ddata$p, status$p) 
DECLARE 

duib$p POINTER, 
ddata$p POINTER, 
statusip POINTER; 


PUBLIC REENTRANT 


DECLARE 
duib 
d info$p 
d inf o 
ddata 
status 
DECLARE 
i 


BASED duib$p DEV$UNIT$INFO$BLOCK, 
POINTER, 

BASED dinfo$p I 206$DEVICE$INFO, 
BASED ddata$p IO$PARM$BLOCK$206 , 
BASED statusip WORD; 

WORD; 


dinfo$p = duib.device$ info$p; 

/* 

* Reset iSBC 206 controller. 
*/ 

output ( reset$port) = 0; 
status = E$OK; 

ddata . restore = FALSE; 

END i206$init; 


179 1 END i206ds; 


MODULE INFORMATION; 


CODE AREA SIZE 

3 

036AH 

874D 

CONSTANT 

AREA 

SIZE = 

0000H 

0D 

VARIABLE 

AREA 

SIZE = 

0000H 

0D 

MAXIMUM 

STACK 

SIZE = 

0046H 

70D 


1101 LINES READ 
0 PROGRAM WARNINGS 
0 PROGRAM ERRORS 

END OF PL/M-86 COMPILATION 
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PL/M-86 COMPILER i206io.p86: iSBC 206 controller I/O Module 

Module Header 

SERIES-III PL/M-86 DEBUG X119 COMPIL^TION OF MODULE I206IO 
OBJECT MODULE PLACED IN ; F5 : 1 20610 . OBJ 

COMPILER INVOKED BY: PLM86.86 : F5 : 1 20610. P86 COMPACT NOTYPE OPTIMIZE (3) ROM 


1 


31 1 


$ ti t le ( ' i 206 io . p86 : iSBC 206 controller I/O Module') 
$subtitle ( 'Module Header') 
i206io: DO; 

/* 

* This module modifies the 206 parameter block 

* and passes the address of it to 

* the iSBC 206 controller. 

* 

* CONTAINS: 

* io$206 

* 

* LANGUAGE DEPENDENCIES; COMPACT ROM OPTIMIZE (3) 

*/ 

$ include( : f 1; ioomon.l it) * 

$save nolist 
$ include (; f 1 ; inutyp.l it) 

$save nolist 
$include(;fl; i iotyp.l it) 

$save nolist 
$ include (; f 1 : i pa ram. 1 it) 

$save nolist 
$include(:fl; i206dv.lit) 

$save nolist 

$include(:fl; i205in.lit) 

$save nolist 
$include(;fl; iiors.lit) 

$save nolist 
$include(;fl; Iduib.lit) 

$save nolist 
$include(:fl;itrsec.lit) 

$save nolist 
$ include( ; f 1; iexcep.l it) 

$save nolist 
$include(:fl; iioexc.lit) 

$save nolist 

$include(:fl; i206dc.ext) 

$save nolist 


/^ 


* This module does the normal io (read, writes and seeks). 

* Formatting a track is handled by i206fm.p86. 

*/ 


DECLARE 

i206$op$codes (*) BYTE DATA( 
READ$0P, 

WRITE$0P, 


PL/M-86 COMPILER i206io.p86: iSBC 206 controller I/O Module 

Module Header 


SEEK$0P 

); 
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PL/M-86 COMPILER i206io.p86; iSBC 206 controller I/O Module 

io$206: iSBC 206 controller I/O Module 


32 1 

33 2 


34 2 


lsubtitle( ' io$206: iSBC 

206 controller I/O Module') 

/* 



* 

io$206 


* 

* 

I/O module 

( read/write/seek) 

* 

CALLING SEQUENCE 

. 

* 

* 

CALL ioS206 

(base, iors$p, duib$p, iopb$p); 

* 

INTERFACE VARIABLES; 

* 

base 

- base address of the board. 

* 

iors$p 

- I/O Request/Result segment pointer 

* 

d u i b$ p 

- pointer to Device-Unit Information Block 

* 

* 

iopb$p 

- pointer to I/O parameter block. 

* 

INTERNAL VARIABLES; 

* 

iors 

- I/O Request/Result Structure. 

* 

ts 

- DWORD containing track and sector info. 

* 

ts$o 

- overlay of ts to allow access through 

* 


PL/M-86. 

* 

duib 

- Device Unit Information Block Structure. 

* 

iopb 

- I/O parameter block for the 

* 


iSBC 206 controller. 

•k 

platter 

- local var to prevent multiple computations. 

* 

spindle 

- as above. 

* 

k 

surface 

- as above. 

k 

CALLS; 


k 

k 

send$206$ iopb(base, @iopb) 

k 

ABSTRACT; 


k 

All io functions (except format) are handled by this 

* 

module. 


* 



io$206; PROCEDURE (base, iors$p, duib$p, iopb$p) REENTRANT PUBLIC 


DECLARE 



base 

WORD, 


iors$p 

POINTER, 


dulb$p 

POINTER, 


iopb$p 

POINTER; 


DECLARE 



•iors 

BASED iors$p IO$REQ$RES$SEG, 


ts 

DWORD, 


ts$o 

TRACK$SECTOR$STRUCT AT(@ts), 


duib 

BASED duib$p DEV$UNIT$INFO$BLOCK , 


iopb 

BASED iopb$p IO$PARM$BLOCK$206, 


platter 

BYTE, 


spindle 

BYTE, 


surface 

BYTE; 


/* 

* Initialize local variables; 

* ts < — track and sector info 

* platter < — from lors.unit. 

* spindle < — from iors.iinit. 

* surface < — from high bit in 
*/ 


from iors.dev$ loc. 


track field. 
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PL/M-86 compiler i206io.p86: iSBC 206 controller I/O Module 

io$206: iSBC 206 controller I/O Module 


36 2 

37 2 

38 2 


ts = iors .dev$ loc; 

spindle = shr ( iors. unit, 2); /* 4 units/spindle */ 

platter = iors. unit AND 003H; /* (as above ) */ 

surface = ts$o. track AND 00001H; /* select surface */ 


43 2 


44 2 


45 2 


* Fill out the iopb for the iSBC 206 controller. 

*/ 

iopb. inter = INTER$ON$MASK; /* we use interrupts */ 

iopb.cyl$add = shr ( ts$o. track , 1); /* track/2 = cylinder */ 


* Note that the iopb.instr field is used by 

* the iSBC 206 controller to determine which 

* drive/platter/surface combination to access 

* AND the op code determines 

* how that combination is to be accessed. 

*/ 

iopb.instr = i206$op$codes ( iors. f unct) OR 
shl(spindle, 4) OR 
shl(platter, 6) OR 
shKsurface, 3); 


* note: the controller only supports 512 

* or 128 byte sectors so no checking is done. 
*/ 

/* divide by sectors size */ 
iopb.rScount = iors. count / duib.dev$gran; 


* sectors come in based on 0 and the controller 

* will only understand sectors starting at 1. 

*/ 

/* (cyl AND 0100H) / 2 */ 
iopb.rec$add = (ts$o. sector + 1) OR 

shr (ts$o. track AND 0200H, 2); 

iopb.buff$p = iors.buffSp; 

IF NOT send$206$iopb(base, @iopb) THEN 

/* 

* the board did not accept the iopb so... 

*/ 

DO; 

iors. status = TO$SOEff; 
iors. actual = 0; 
iors. done = TRUE; 

END; 


END io$206; 


END i206io; 


PL/M-86 COMPILER i206io.p86: iSBC 206 controller I/O Module 

io$206: iSBC 206 controller I/O Module 


MODULE INFORMATION: 

CODE AREA SIZE = 00DBH 219D 

CONSTANT AREA SIZE =■ 0000H 0D 

VARIABLE AREA SIZE = 0000H 0D 

MAXIMUM STACK SIZE = 0022H 34D 

615 LINES READ 
0 PROGRAM WARNINGS 
0 PROGRAM ERRORS 


END OF PL/M-86 COMPILATION 
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PL/M-86 compiler i206dc: iSBC 206 controller parameter handler 

Module Header 


SERTES-III PL/M-86 DEBUG X119 COMPILATION OF MODULE I206DC 
OBJECT MODULE PLACED IN : F5 : I 206DC . OBJ 

COMPILER INVOKED BY: PLM86.86 : F5 ; I 206DC . P86 COMPACT NOTYPE OPTIMIZE(3) ROM 


$title( ’ i206dc: iSBC 206 controller parameter handler') 
$subtitle ( 'Module Header') 

1 i206dc: DO; 

/* 

* i206dc.p86 

* 

* CONTAINS: 

* send$206$ iopb 

* 

* LANGUAGE DEPENDENCIES: COMPACT ROM OPTIMIZE (3) 

*/ 

$ include (: fl : icomon. 1 it) 

= $save nolist 

$include(:fl: inutyp.lit) 

= $save nolist 

$ include ( : f 1 : i206dv. 1 i t) 

= $save nolist 
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PL/M-86 COMPILER i206dc: iSBC 206 controller parameter handler 

Send 206 I/O Parameter Block 


8 1 

9 2 

10 2 


11 2 
12 2 


13 2 

14 2 

15 3 


16 3 

17 3 


18 4 

19 4 


$subti tie (' Send 206 I/O Parameter Block') 

/* 

* send$206$ iopb 

* send the iSBC 206 controller the address of the parameter block 

* 

* CALLING SEQUENCE; 

* CALL send$206$ iopb (base, iopb$p) ; 

* 


* INTERFACE VARIABLES: 

* base - base address of board. 

* iopb$p - I/O parameter block pointer 

* 

* INTERNAL VARIALBLES: 

* iopb$p$o - overlay for the pointer. 

* iopb - I/O parameter block structure. 

* drive - local var to reduce computations. 

* 


* CALLS; 

* <none> 

* 

* ABSTRACT; 

* outputs the iopb to the iSBC 206 controller. 

*/ 

send$206$iopb: PROCEDURE (base, iopb$p) BOOLEAN REENTRANT PUBLIC; 
DECLARE 

base WORD, 

iopb$p POINTER; 


DECLARE 

iopb$p$o P$OVERLAY AT(0iopb$p) , 

iopb BASED iopb$p IO$PARM$BLOCK$206 , 

drive BYTE; 


/* 

* Extract the drive unit from the instruction. 

*/ 

drive = shr ( iopb. instr AND 030H, 4); 
drive = shl (01H, drive) ; 

/* 

* Check to see if the drive is busy. 

*/ 

IF (input (controller$stat) ) <> (COMMAND$BUSY OR drive) THEN 
DO; 

output ( lo$of f $port) = low ( iopb$p$o. offset) ; 

/* 

* Check to see if the drive is busy AGAIN. 

*/ 

IF ( input (controllers stat) AND COMMAND$BUSY) = 0 THEN 
DO; 

/* 

* made it to here so 

* output rest of iopb address. 

*/ 

output ( lo$seg$port) = low ( iopb$p$o.base) ; 
output (hi$seg$port) =» high ( iopb$p$o.base) ; 
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PL/M-86 COMPILER i206dc: iSBC 206 controller parameter handler 

Send 206 I/O Parameter Block 


20 4 output (hi$of fSport) = high ( iopb$p$o.of Eset) ; 

21 4 RETURN (TRUE) ; 

22 4 END; 

23 3 END; 

/* 

* If we got here then something blew up. 

* So inform the caller that we could not process the iopb. 

*/ 

24 2 RETURN (FALSE); 

25 2 END send$206$ iopb; 

26 1 END i206dc; 


module INFORMATION: 

CODE AREA SIZE = 0066H 102D 

CONSTANT AREA SIZE = 0000H 0D 

VARIABLE AREA SIZE = 0000H 0D 

MAXIMUM STACK SIZE = 000CH 12D 

216 LINES READ 
0 PROGRAM WARNINGS 
0 PROGRAM ERRORS 

END OF PL/M-86 COMPILATION 
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PL/M-86 compiler i206fm.p86 

Module Header 


SERIES-III PL/M-86 DEBUG X119 COMPILATION OF MODULE I206FM 
OBJECT MODULE PLACED IN : F5 : I 206FM. OBJ 

COMPILER INVOKED BY: PLM86.86 : F5: I206FM. P86 COMPACT NOTYPE OPTIMIZE(3) ROM 


$title( ' i206fm.p86 ' ) 

$subtitle( 'Module Header*) 

/* 

* i206fm.p86 

* 

* CONTAINS: 

* fonnat$206 

* build206$$fmt$table 

* 

* LANGUAGE DEPENDENCIES: COMPACT ROM OPTIMIZE (3) 

*/ 

1 i206fm: DO; 

$ include (: f 1 : icotnon.l it) 

= $save nolist 

$include(:fl: i nutyp.l it) 

= $save nolist 

$include(:fl:i iotyp.l it) 

= $save nolist 

$include(:fl: i pa ram. lit) 

= $save nolist 

$include(:fl:i206dv.lit) 

= $save nolist 

$include(:fl:i206in.lit) 

= $save nolist 

$include(:fl:iradsf.lit) 

= $save nolist 

$include(:fl: iiors.lit) 

= $save nolist 

$include(:fl:iduib.lit) 

= $save nolist 

$ include( : f 1: itrsec.lit) 

= $save nolist 

$ include (: f 1 : iexcep.l it) 

= $save nolist 

$include(:fl:iioexc.lit) 

= $save nolist 

$include(;fl:1206dc.ext) 

= $save nolist 
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PL/M-86 COMPILER 


i206fm.p86 

format$206; Format track procedure 


34 1 

35 2 


36 2 


37 2 

38 2 

39 2 


40 3 

41 3 

42 3 


$subtitle ( ' format$206: Format track procedure') 

/* 

* format$206 

* format a track on the iSBC 206 controller. 

* 

* CALLING SEQUENCE: 

* CALL format$206 (base, iors$p, duib$p, iopb$p); 

* 


* 

* 

* 

* 

* 

* 


INTERFACE VARIABLES 
base 
iors$p 

duib$p - 

iopb$p 


base address of board. 

I/O Request/Result segment 
pointer to Device-Unit Inf 
I/O parameter block pointe 


pointer 

ormation Block 

r . 


* CALLS: 

* build$206$frot$ table 

* send$206$ iopb 

* 

* CALLED FROM: 

* i206$start 

* 


* ABSTRACT: 

* this procedure will format a 

* It will not format the other 

*/ 

format$206: PROCEDURE (base, iors$p, 
DECLARE 


single track on the disk, 
side of the cylinder. 

duib$p, iopb$p) 

REENTRANT PUBLIC; 


base WORD, 

iors$p POINTER, 

duib$p POINTER, 

iopb$p POINTER; 


DECLARE 

iors 

f ormat$ inf o$ 

f ormat$ info 

duib 

iopb 

platter 

spindle 

surface 

max$ sectors 


BASED iors$p IO$REQ$RES$SEG, 
p POINTER, 

BASED format$info$p FORMAT$INFO$STRUCT 
BASED duib$p DEV$UNIT$INFO$BLOCK, 

BASED iopb$p IO$PARM$BLOCK$206, 

BYTE, 

BYTE, 

BYTE, 

BYTE; 


/* 

* initialize local variables. 

*/ 

f ormat$ info$p = iors.aux$p; 

IF format$ info. track$num > i205$TRACK$MAX THEN 
DO; 

/* 

* Let's leave now since we cannot 


* access any 
*/ 

tracks . 

ors. status 

= 

E$SPACE 

ors. actual 


0; 

ors. done = 

TRUE; 
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PL/M-86 COMPILER i206fm.p86 

format$206: Format track procedure 


43 3 

44 3 


45 2 

46 2 

47 2 


48 2 


49 2 


50 2 

51 2 


52 2 

53 2 

54 2 


55 2 


56 2 


57 2 


58 2 

59 3 

60 3 

61 3 


RETURN; 


END; 


* use local variables to eliminate later confusion. 

*/ 


spindle 

= sh 

r ( iors. unit , 

2); 

/* 

4 units/spindle */ 

platter 

= io 

rs.unit AND 

003H; 

/* 

(as above ) */ 

surface 

= fo 

rmatS info. t r 

ackSnum AND 





00001H; 


/* 

select surface */ 

/* 






* fill 

out 

the IOPB for 

the ioS206. 




*/ 

iopb. inter = INTER$ON$MASK OR PORMAT$TRACK$ON ; 

/* track/2 = cylinder */ 

iopb.cyl$add = shr ( f ormat$ info. t rack$num , 1); 

/* set bit if over 256 cylinders */ 

iopb.rec$add = shr ( f ormat$ inf o. t rack$num AND 0200H, 2); 
iopb.instr = formatSop OR 

shl(spindle, 4) OR 
shl(platter, 6) OR 
shl(surface, 3); 

iopb.buff$p = 0iopb. formats table; 

IF duib.devSgran = 128 THEN 
maxSsectors = 36; 

ELSE 

/* 

* if not 128 then MUST be 512 byte sectors 

*/ 

maxSsectors = 12; 


/* 


* 

the 

* 

the 

* 

so 

* 

/ 


CALL buildS206$fmt$ table (@iopb. formats table , 

formats info.trackSnum, 
formats inf o. trackS inter leave, 
formats info.trackSskew, 
formats info. f illSchar, 
maxS sectors) ; 

IF NOT send$206$ iopb(base, 0iopb) THEN 

/* 

* the board did not accept the iopb so... 

*/ 


DO; 


iors. status = lOSSOFT; 


iors. actual 


0 ; 


iors. done = TRUE; 


PL/M-86 COMPILER i206fm.p86 

formatS206: Format track procedure 

62 3 END; 

63 2 END formatS206; 
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PL/M-86 COMPILER i206fm.p86 

format$206: Format track procedure 


64 1 


65 2 


66 2 


67 2 


68 2 

69 3 

70 3 

71 3 


$e j ect 
/* 

* bui ld$206$ fmt$ table 

* fill out format table 


* CALLING SEQUENCE: 

* CALL build$206$fmt$table(buf$p, 

* track, 

* int$fact, 

* skew, 

* fill$char, 

* max$ sectors) ; 


* 

* 

* 

4r 

* 

* 

* 

* 


INTERFACE VARIABLES; 

buf$p - address of format table, 

track - track to be formatted, 

int$fact - interleave factor, 

skew - squew from physical sector one, 

fill$char - used to fill sectors. 
max$sectors - maximum number of sectors 


* CALLS: 

* <none> 

* 

* No error checking on skew, int$fact parameters; 

* if nonsense, the algorithm completes & formats 

* the track in a strange manner. 

*/ 


build$206$fmt$table; PROCEDURE (buf$p , track, intSfact, skew, 

f i 11$ char ,max$ sectors) REENTRANT; 

DECLARE 


buf $p 

POINTER 

track 

WORD, 

int$ fact 

BYTE, 

skew 

BYTE, 

f i llSchar 

BYTE, 

max$ sectors 

BYTE; 

DECLARE 


s 

BYTE, 

i 

BYTE; 

DECLARE 



fmt$tab BASED buf$p (36) STRUCTURE ( 
records address BYTE, 
fillSchar BYTE); 

/* 

* fill out the format table with 0FFH, 

* this will be used to indicate when 

* all the record addresses are filled in. 
*/ 

DO i = 0 TO (max$ sectors - 1); 

fmt$ tab ( i) . recordSaddress =* 0FFH; 
fmt$ tab ( i) . f ill$char = fillSchar; 

END; 
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PL/M-86 COMPILER 1206fm.p86 

format$206: Format track procedure 


72 2 s = skew MOD max$sectors; 

73 2 DO i = 1 TO max$sectors; 

74 3 DO WHILE fmt$ tab (s) . record$address <> 0FFH 

75 4 s = (s + 1) MOD max$sectors; 

76 4 END; 

77 3 frat$tab(s) . record$address = i; 

78 3 s = (s + int$fact) MOD max$sectors; 

79 3 END; 

80 2 END build$206$fmt$table; 

81 1 END i206fm; 


MODULE INFORMATION; 

CODE AREA SIZE = 0195H 405D 

CONSTANT AREA SIZE = 0000H 0D 

VARIABLE AREA SIZE = 0000H 0D 

MAXIMUM STACK SIZE = 0028H 40D 

717 LINES READ 
0 PROGRAM WARNINGS 
0 PROGRAM ERRORS 

END OF PL/M-86 COMPILATION 
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